add files
Caleb Fontenot
parent
b4f7a8873b
commit
335515d331
@ -0,0 +1,321 @@
|
||||
Delivered-To: foley2431@gmail.com
|
||||
Received: by 2002:a17:90a:62c9:0:0:0:0 with SMTP id k9csp2454751pjs;
|
||||
Thu, 27 Jun 2019 12:38:59 -0700 (PDT)
|
||||
X-Received: by 2002:a5d:8c81:: with SMTP id g1mr6741349ion.239.1561664339657;
|
||||
Thu, 27 Jun 2019 12:38:59 -0700 (PDT)
|
||||
ARC-Seal: i=1; a=rsa-sha256; t=1561664339; cv=none;
|
||||
d=google.com; s=arc-20160816;
|
||||
b=xwzygQkNBl4RrUe3SLUOiKF7PZxhy8sP1WgDrmfbrfYM84V5UEaqNbp3NmvKeJzMwj
|
||||
/T4ylHAy4x6+qe5E78c+Db+WyrCNwo7MLZgGUm16SXrO4lQRDV2hE2oRep34VzGbywbp
|
||||
S3vYW2tvMRj2sBT4L+grmerBo4J4HO7bu3fBrCth8xDwgVMFcDWKgEDmJqMTSDcti6Zt
|
||||
TSiKIQtoLWeoB0w6TC+Xnxx+N3qxBaGStsJ217Atz9mbwF5gy7pQV5ZIlTbFfclgc5pt
|
||||
bPjqQgr+aLcVpzKRlNNkz1jOlQrhu+Zxkhv1AFBPHrV4ofO7Lrwkp5by0HRj2z9AX+qE
|
||||
z68Q==
|
||||
ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816;
|
||||
h=to:subject:message-id:date:from:in-reply-to:references:mime-version
|
||||
:dkim-signature;
|
||||
bh=nYbTDDD7FDOcAyeQOYg4aeTL1X63lWkIu4z5s6n/X8M=;
|
||||
b=BdTBGL/9qyt1R2BsTWA/mSyXmYOWajowJVGQv9paSMx3pmpM3FpYdtQLFSi8vFVBjN
|
||||
OTA6E6C5DQKxPgrWwAzDD21CoAJtlbVY08b6W4Sy0XU7Oj281/Yufi/DVt0xOVaPAqLd
|
||||
ASYBVOIvzEFHw8OYouCGmEcEEAYyFxcXuzjVJG9DH6GZrju6ezCjhoVsPZX0pbVn8PGE
|
||||
wTe2dLrWxw9h6wuTx+KDuXFRuaDy05+naA++h6p6XQSbZDP+Vu7AFKGgF2gBzq9spB67
|
||||
R449QrBQsLbKy8zB2XTjVzrfZyHRpTgEmwjvzbOwlNiqikMLnSmw+9O3k7UOWr1PFgtH
|
||||
YtCw==
|
||||
ARC-Authentication-Results: i=1; mx.google.com;
|
||||
dkim=pass header.i=@pediatrictlc-com.20150623.gappssmtp.com header.s=20150623 header.b=RWAkpuKx;
|
||||
spf=pass (google.com: domain of allison@pediatrictlc.com designates 209.85.220.41 as permitted sender) smtp.mailfrom=allison@pediatrictlc.com
|
||||
Return-Path: <allison@pediatrictlc.com>
|
||||
Received: from mail-sor-f41.google.com (mail-sor-f41.google.com. [209.85.220.41])
|
||||
by mx.google.com with SMTPS id h73sor2480973iof.22.2019.06.27.12.38.59
|
||||
for <foley2431@gmail.com>
|
||||
(Google Transport Security);
|
||||
Thu, 27 Jun 2019 12:38:59 -0700 (PDT)
|
||||
Received-SPF: pass (google.com: domain of allison@pediatrictlc.com designates 209.85.220.41 as permitted sender) client-ip=209.85.220.41;
|
||||
Authentication-Results: mx.google.com;
|
||||
dkim=pass header.i=@pediatrictlc-com.20150623.gappssmtp.com header.s=20150623 header.b=RWAkpuKx;
|
||||
spf=pass (google.com: domain of allison@pediatrictlc.com designates 209.85.220.41 as permitted sender) smtp.mailfrom=allison@pediatrictlc.com
|
||||
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
|
||||
d=pediatrictlc-com.20150623.gappssmtp.com; s=20150623;
|
||||
h=mime-version:references:in-reply-to:from:date:message-id:subject:to;
|
||||
bh=nYbTDDD7FDOcAyeQOYg4aeTL1X63lWkIu4z5s6n/X8M=;
|
||||
b=RWAkpuKxnJg6AohdfEJv/tzlDQOwcq0wZECjd1hFreSIf+60mbeCCKkxqotM9Lg+sE
|
||||
VWYxDCr7091xAXadjxloW/QWmoD3GOU4Tu4heSfooObaiicb7aYmY6dlXVjSCdJEsDxd
|
||||
4mr/idEDnQIY1qppCnDDpSpaiA08Me7aIjU4CBIRWMVRH25vWWGYjo3j/kRslTKqSphs
|
||||
imdHq0vum0BeC+C9Yt8gqJoL51wHCf8hggArH1oHgdToH9eYA2jQB0DG7FTW7zMutalA
|
||||
UVn/l3B4rR6dOGKbmqo7BXz2mbjl74dEDpEC/9yU4TaY3I40T94EC8CYvHwzr/7r1kEI
|
||||
Z5EQ==
|
||||
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
|
||||
d=1e100.net; s=20161025;
|
||||
h=x-gm-message-state:mime-version:references:in-reply-to:from:date
|
||||
:message-id:subject:to;
|
||||
bh=nYbTDDD7FDOcAyeQOYg4aeTL1X63lWkIu4z5s6n/X8M=;
|
||||
b=dk44IpPiycZmUEXFojs8OUTzsG8QOkHUCD6O+osQaBrUCYRO81FkosO+YWH2ArqgMg
|
||||
QVSV9kqBr73jeEIC1wLaYPEU9XYs3MIr29B7VRJFUe6A6mUiH48OyekwGvrsL4EI68A8
|
||||
cvGO8Pnp5dqiBXMOLofRRZsmikX5XkymHI7S9JuSGxaNT7afgS2IzlcWKI+Qsr6Py4dP
|
||||
XU5ftImgffmaE3pE26UP8Kp3/QUK7xjjjhxo1DnCThFqiez2qtp65mSWvmH0kdOqq5kO
|
||||
Z3yf2LZdmNyJobmlQBZRu50yNH25WoPHoXO0tZBJ+zw3lvOztD0S2i2v4D9APx48wWZh
|
||||
PL6A==
|
||||
X-Gm-Message-State: APjAAAVQ8Du7W67tJzbWI4CEGdZbTiifWElaj6X90wzWIW+SgV03Sw1w
|
||||
lDVmGKaNgxECarZphrJ8BjA1nSFD4iDlB6FqsBa91Fwy
|
||||
X-Google-Smtp-Source: APXvYqwBIap+WFhQUS6PQI4MjFopvdAdUzZTvgT6LsgOFDvc7GvdJiPZMbjWw/nw0MMc8+pVW8ODUXrfuDgx7nYKMPs=
|
||||
X-Received: by 2002:a6b:6f0e:: with SMTP id k14mr6492400ioc.257.1561664338861;
|
||||
Thu, 27 Jun 2019 12:38:58 -0700 (PDT)
|
||||
MIME-Version: 1.0
|
||||
References: <CAKC1GZMw27BuUN8oXwD2TvbOH3BW4EfDnz_ATZrX1phXk6Z0yg@mail.gmail.com>
|
||||
<BD8BCA5E-FACB-45F8-8AF7-94EEF2371B19@pediatrictlc.com> <CAKC1GZMJMe92ftWbG1cpOyzOvZPmYkG6BtwYz2XWOvzM7_SH6A@mail.gmail.com>
|
||||
In-Reply-To: <CAKC1GZMJMe92ftWbG1cpOyzOvZPmYkG6BtwYz2XWOvzM7_SH6A@mail.gmail.com>
|
||||
From: Allison LeBouef <allison@pediatrictlc.com>
|
||||
Date: Thu, 27 Jun 2019 14:38:46 -0500
|
||||
Message-ID: <CAEuKE+65LdbHaTHnXVXb5ZK6XLsHQgqxT1QSdQh=Zm2m6dDqNA@mail.gmail.com>
|
||||
Subject: Fwd: programming project
|
||||
To: foley2431@gmail.com
|
||||
Content-Type: multipart/alternative; boundary="0000000000002d3380058c535034"
|
||||
|
||||
--0000000000002d3380058c535034
|
||||
Content-Type: text/plain; charset="UTF-8"
|
||||
Content-Transfer-Encoding: quoted-printable
|
||||
|
||||
---------- Forwarded message ---------
|
||||
From: Andy LeGoullon <andylegoullon@gmail.com>
|
||||
Date: Thu, Jun 20, 2019 at 12:14 AM
|
||||
Subject: Re: programming project
|
||||
To: Allison LeBouef <allison@pediatrictlc.com>
|
||||
|
||||
|
||||
Here's the MadLibs project I give to my students. If Caleb wants to do this
|
||||
project, have him do as much as he can on his own and then he can email me
|
||||
with questions when he gets stuck. If he'd rather do some other project
|
||||
that he thinks up, I could help him with that too.
|
||||
|
||||
Andy
|
||||
|
||||
Programming Project: MadLibs
|
||||
|
||||
|
||||
1.
|
||||
|
||||
Write a MadLibs story containing 10 or so prompts (words you will ask
|
||||
the user to enter, for example a noun, a country, a snack food, etc). Th=
|
||||
e
|
||||
story can be about anything you want: How to catch a fish, how to bake a
|
||||
cake, what happens during a trip to Disney World, etc.
|
||||
2.
|
||||
|
||||
Make a file called madlibs.py. This file will contain all the python
|
||||
code to play your Madlibs. Add code to this file that does the following=
|
||||
:
|
||||
1.
|
||||
|
||||
Asks the first prompt, for example, "Enter the name of a vegetable"
|
||||
2.
|
||||
|
||||
Store the user's entered word in a variable.
|
||||
3.
|
||||
|
||||
Repeat these two tasks for all the remaining prompts.
|
||||
4.
|
||||
|
||||
Print out the completed MadLibs story, replacing the prompts with the
|
||||
words stored in the variables.
|
||||
3.
|
||||
|
||||
Run your program and make sure it works correctly.
|
||||
|
||||
|
||||
|
||||
On Fri, Jun 14, 2019 at 9:48 AM Allison LeBouef <allison@pediatrictlc.com>
|
||||
wrote:
|
||||
|
||||
> I love Madlibs! I like the idea of getting him to formulate the questions
|
||||
> he needs to ask too. Let=E2=80=99s try it and see what happens! Thanks so=
|
||||
much for
|
||||
> helping me with this
|
||||
> Allison
|
||||
>
|
||||
> Sent from my iPhone
|
||||
>
|
||||
> > On Jun 14, 2019, at 8:55 AM, Andy LeGoullon <andylegoullon@gmail.com>
|
||||
> wrote:
|
||||
> >
|
||||
> > Are you familiar with Madlibs? I was thinking of having Caleb make a
|
||||
> computer program version of Madlibs as his first project. It's more of an
|
||||
> intermediate level project, but not impossible for someone starting out a=
|
||||
nd
|
||||
> it sounds like he's looking for a challenge. I can give you the project
|
||||
> details if you think this would work out.
|
||||
> >
|
||||
> > He would definitely need some assistance on it at times, but it would
|
||||
> give him good experience asking for help. I could help him out via
|
||||
> email/phone. Or I can come in if he is getting very frustrated. Anna know=
|
||||
s
|
||||
> Python and may also be willing to help.
|
||||
> >
|
||||
> > Andy
|
||||
>
|
||||
|
||||
|
||||
--=20
|
||||
Allison LeBouef, LOTR/ OT supervisor
|
||||
Pediatric Therapy and Learning Center, LLC
|
||||
108 Energy Pkwy
|
||||
Lafayette, LA 70508
|
||||
(337)504-4244
|
||||
fax (337)706-7612
|
||||
www.pediatrictlc.com
|
||||
|
||||
*Important Confidentiality Information:*
|
||||
|
||||
The information contained in this transmission may contain privileged and
|
||||
confidential information, including patient information protected by
|
||||
federal and state privacy laws. It is intended only for the use of the
|
||||
person(s) named above. If you are not the intended recipient, any review,
|
||||
dissemination, distribution, or duplication of this communication is
|
||||
strictly prohibited. If you are not the intended recipient, please contact
|
||||
the sender by calling 337-504-4244 <(337)%20504-4244>. Feel free to leave
|
||||
a voice message stating the sender and the subject line. Please destroy all
|
||||
copies of the original message.
|
||||
|
||||
Clients: Please note that this is not an encrypted email which means that
|
||||
the e-mail and any information it contains could be unknowingly
|
||||
intercepted. Please consider this in all future correspondence.
|
||||
|
||||
--0000000000002d3380058c535034
|
||||
Content-Type: text/html; charset="UTF-8"
|
||||
Content-Transfer-Encoding: quoted-printable
|
||||
|
||||
<div dir=3D"ltr"><br><br><div class=3D"gmail_quote"><div dir=3D"ltr" class=
|
||||
=3D"gmail_attr">---------- Forwarded message ---------<br>From: <strong cla=
|
||||
ss=3D"gmail_sendername" dir=3D"auto">Andy LeGoullon</strong> <span dir=3D"a=
|
||||
uto"><<a href=3D"mailto:andylegoullon@gmail.com">andylegoullon@gmail.com=
|
||||
</a>></span><br>Date: Thu, Jun 20, 2019 at 12:14 AM<br>Subject: Re: prog=
|
||||
ramming project<br>To: Allison LeBouef <<a href=3D"mailto:allison@pediat=
|
||||
rictlc.com">allison@pediatrictlc.com</a>><br></div><br><br><div dir=3D"l=
|
||||
tr">Here's the MadLibs project I give to my students. If Caleb wants to=
|
||||
do this project, have him do as much as he can on his own and then he can =
|
||||
email me with questions when he gets stuck. If he'd rather do some othe=
|
||||
r project that he thinks up, I could help him with that too.=C2=A0<div><br>=
|
||||
</div><div>Andy</div><div><br></div><div><span id=3D"m_-3611317769460724002=
|
||||
gmail-docs-internal-guid-61d5ccb3-7fff-4947-19e4-7ad848c11bb7"><p dir=3D"lt=
|
||||
r" style=3D"line-height:1.38;margin-top:0pt;margin-bottom:0pt;text-align:ce=
|
||||
nter"><span style=3D"font-size:11pt;font-family:Arial;color:rgb(0,0,0);back=
|
||||
ground-color:transparent;font-weight:700;font-variant-numeric:normal;font-v=
|
||||
ariant-east-asian:normal;vertical-align:baseline;white-space:pre-wrap">Prog=
|
||||
ramming Project: MadLibs</span></p><br><ol style=3D"margin-top:0pt;margin-b=
|
||||
ottom:0pt"><li dir=3D"ltr" style=3D"list-style-type:decimal;font-size:10pt;=
|
||||
font-family:Arial;color:rgb(0,0,0);background-color:transparent;font-varian=
|
||||
t-numeric:normal;font-variant-east-asian:normal;vertical-align:baseline;whi=
|
||||
te-space:pre-wrap"><p dir=3D"ltr" style=3D"line-height:1.38;margin-top:0pt;=
|
||||
margin-bottom:0pt"><span style=3D"font-size:10pt;background-color:transpare=
|
||||
nt;font-variant-numeric:normal;font-variant-east-asian:normal;vertical-alig=
|
||||
n:baseline;white-space:pre-wrap">Write a MadLibs story containing 10 or so =
|
||||
prompts (words you will ask the user to enter, for example a noun, a countr=
|
||||
y, a snack food, etc). The story can be about anything you want: How to cat=
|
||||
ch a fish, how to bake a cake, what happens during a trip to Disney World, =
|
||||
etc.</span></p></li><li dir=3D"ltr" style=3D"list-style-type:decimal;font-s=
|
||||
ize:10pt;font-family:Arial;color:rgb(0,0,0);background-color:transparent;fo=
|
||||
nt-variant-numeric:normal;font-variant-east-asian:normal;vertical-align:bas=
|
||||
eline;white-space:pre-wrap"><p dir=3D"ltr" style=3D"line-height:1.38;margin=
|
||||
-top:0pt;margin-bottom:0pt"><span style=3D"font-size:10pt;background-color:=
|
||||
transparent;font-variant-numeric:normal;font-variant-east-asian:normal;vert=
|
||||
ical-align:baseline;white-space:pre-wrap">Make a file called </span><span s=
|
||||
tyle=3D"font-size:10pt;background-color:transparent;font-weight:700;font-va=
|
||||
riant-numeric:normal;font-variant-east-asian:normal;vertical-align:baseline=
|
||||
;white-space:pre-wrap">madlibs.py</span><span style=3D"font-size:10pt;backg=
|
||||
round-color:transparent;font-variant-numeric:normal;font-variant-east-asian=
|
||||
:normal;vertical-align:baseline;white-space:pre-wrap">. This file will cont=
|
||||
ain all the python code to play your Madlibs. Add code to this file that do=
|
||||
es the following:</span></p></li><ol style=3D"margin-top:0pt;margin-bottom:=
|
||||
0pt"><li dir=3D"ltr" style=3D"list-style-type:lower-alpha;font-size:10pt;fo=
|
||||
nt-family:Arial;color:rgb(0,0,0);background-color:transparent;font-variant-=
|
||||
numeric:normal;font-variant-east-asian:normal;vertical-align:baseline;white=
|
||||
-space:pre-wrap"><p dir=3D"ltr" style=3D"line-height:1.38;margin-top:0pt;ma=
|
||||
rgin-bottom:0pt"><span style=3D"font-size:10pt;background-color:transparent=
|
||||
;font-variant-numeric:normal;font-variant-east-asian:normal;vertical-align:=
|
||||
baseline;white-space:pre-wrap">Asks the first prompt, for example, "En=
|
||||
ter the name of a vegetable"</span></p></li><li dir=3D"ltr" style=3D"l=
|
||||
ist-style-type:lower-alpha;font-size:10pt;font-family:Arial;color:rgb(0,0,0=
|
||||
);background-color:transparent;font-variant-numeric:normal;font-variant-eas=
|
||||
t-asian:normal;vertical-align:baseline;white-space:pre-wrap"><p dir=3D"ltr"=
|
||||
style=3D"line-height:1.38;margin-top:0pt;margin-bottom:0pt"><span style=3D=
|
||||
"font-size:10pt;background-color:transparent;font-variant-numeric:normal;fo=
|
||||
nt-variant-east-asian:normal;vertical-align:baseline;white-space:pre-wrap">=
|
||||
Store the user's entered word in a variable.</span></p></li><li dir=3D"=
|
||||
ltr" style=3D"list-style-type:lower-alpha;font-size:10pt;font-family:Arial;=
|
||||
color:rgb(0,0,0);background-color:transparent;font-variant-numeric:normal;f=
|
||||
ont-variant-east-asian:normal;vertical-align:baseline;white-space:pre-wrap"=
|
||||
><p dir=3D"ltr" style=3D"line-height:1.38;margin-top:0pt;margin-bottom:0pt"=
|
||||
><span style=3D"font-size:10pt;background-color:transparent;font-variant-nu=
|
||||
meric:normal;font-variant-east-asian:normal;vertical-align:baseline;white-s=
|
||||
pace:pre-wrap">Repeat these two tasks for all the remaining prompts.</span>=
|
||||
</p></li><li dir=3D"ltr" style=3D"list-style-type:lower-alpha;font-size:10p=
|
||||
t;font-family:Arial;color:rgb(0,0,0);background-color:transparent;font-vari=
|
||||
ant-numeric:normal;font-variant-east-asian:normal;vertical-align:baseline;w=
|
||||
hite-space:pre-wrap"><p dir=3D"ltr" style=3D"line-height:1.38;margin-top:0p=
|
||||
t;margin-bottom:0pt"><span style=3D"font-size:10pt;background-color:transpa=
|
||||
rent;font-variant-numeric:normal;font-variant-east-asian:normal;vertical-al=
|
||||
ign:baseline;white-space:pre-wrap">Print out the completed MadLibs story, r=
|
||||
eplacing the prompts with the words stored in the variables.</span></p></li=
|
||||
></ol><li dir=3D"ltr" style=3D"list-style-type:decimal;font-size:10pt;font-=
|
||||
family:Arial;color:rgb(0,0,0);background-color:transparent;font-variant-num=
|
||||
eric:normal;font-variant-east-asian:normal;vertical-align:baseline;white-sp=
|
||||
ace:pre-wrap"><p dir=3D"ltr" style=3D"line-height:1.38;margin-top:0pt;margi=
|
||||
n-bottom:0pt"><span style=3D"font-size:10pt;background-color:transparent;fo=
|
||||
nt-variant-numeric:normal;font-variant-east-asian:normal;vertical-align:bas=
|
||||
eline;white-space:pre-wrap">Run your program and make sure it works correct=
|
||||
ly.</span></p></li></ol></span></div><div><br></div></div><br><div class=3D=
|
||||
"gmail_quote"><div dir=3D"ltr" class=3D"gmail_attr">On Fri, Jun 14, 2019 at=
|
||||
9:48 AM Allison LeBouef <<a href=3D"mailto:allison@pediatrictlc.com" ta=
|
||||
rget=3D"_blank">allison@pediatrictlc.com</a>> wrote:<br></div><blockquot=
|
||||
e class=3D"gmail_quote" style=3D"margin:0px 0px 0px 0.8ex;border-left:1px s=
|
||||
olid rgb(204,204,204);padding-left:1ex">I love Madlibs! I like the idea of =
|
||||
getting him to formulate the questions he needs to ask too. Let=E2=80=99s t=
|
||||
ry it and see what happens! Thanks so much for helping me with this<br>
|
||||
Allison<br>
|
||||
<br>
|
||||
Sent from my iPhone<br>
|
||||
<br>
|
||||
> On Jun 14, 2019, at 8:55 AM, Andy LeGoullon <<a href=3D"mailto:andy=
|
||||
legoullon@gmail.com" target=3D"_blank">andylegoullon@gmail.com</a>> wrot=
|
||||
e:<br>
|
||||
> <br>
|
||||
> Are you familiar with Madlibs? I was thinking of having Caleb make a c=
|
||||
omputer program version of Madlibs as his first project. It's more of a=
|
||||
n intermediate level project, but not impossible for someone starting out a=
|
||||
nd it sounds like he's looking for a challenge. I can give you the proj=
|
||||
ect details if you think this would work out.<br>
|
||||
> <br>
|
||||
> He would definitely need some assistance on it at times, but it would =
|
||||
give him good experience asking for help. I could help him out via email/ph=
|
||||
one. Or I can come in if he is getting very frustrated. Anna knows Python a=
|
||||
nd may also be willing to help. <br>
|
||||
> <br>
|
||||
> Andy<br>
|
||||
</blockquote></div>
|
||||
</div><br clear=3D"all"><div><br></div>-- <br><div dir=3D"ltr" class=3D"gma=
|
||||
il_signature" data-smartmail=3D"gmail_signature"><div dir=3D"ltr"><div><div=
|
||||
dir=3D"ltr"><div dir=3D"ltr"><div dir=3D"ltr"><div><span style=3D"font-siz=
|
||||
e:12.8px">Allison LeBouef, LOTR/ OT supervisor</span><br></div>
|
||||
<div>Pediatric Therapy and Learning Center, LLC</div>
|
||||
<div>108 Energy Pkwy</div>
|
||||
<div>Lafayette, LA=C2=A0 70508</div><div>(337)504-4244</div><div>fax (337)7=
|
||||
06-7612</div><div><a href=3D"http://www.pediatrictlc.com" target=3D"_blank"=
|
||||
>www.pediatrictlc.com</a></div><div><br></div><div><p style=3D"font-family:=
|
||||
arial,"san serif";font-size:12.8px"><strong>Important Confidentia=
|
||||
lity Information:</strong></p><p style=3D"font-family:arial,"san serif=
|
||||
";font-size:12.8px">The information contained in this transmission may=
|
||||
contain privileged and confidential information, including patient informa=
|
||||
tion protected by federal and state privacy laws. It is intended only for t=
|
||||
he use of the person(s) named above. If you are not the intended recipient,=
|
||||
any review, dissemination, distribution, or duplication of this communicat=
|
||||
ion is strictly prohibited. If you are not the intended recipient, please c=
|
||||
ontact the sender by calling=C2=A0<a href=3D"tel:(337)%20504-4244" value=3D=
|
||||
"+13375044244" style=3D"color:rgb(17,85,204)" target=3D"_blank">337-504-424=
|
||||
4</a>.=C2=A0 Feel free to leave a voice message stating the sender and the =
|
||||
subject line. Please destroy all copies of the original message.</p><p styl=
|
||||
e=3D"font-family:arial,"san serif";font-size:12.8px">Clients: Ple=
|
||||
ase note that this is not an encrypted email which means that the e-mail an=
|
||||
d any information it contains could be unknowingly intercepted.=C2=A0 Pleas=
|
||||
e consider this in all future correspondence.=C2=A0</p></div></div></div></=
|
||||
div></div></div></div></div>
|
||||
|
||||
--0000000000002d3380058c535034--
|
||||
@ -0,0 +1,83 @@
|
||||
# Toggle me for debugging
|
||||
debug = 1
|
||||
|
||||
# Import the libraries we will use
|
||||
import re
|
||||
import sys
|
||||
import random
|
||||
import platform
|
||||
import argparse
|
||||
# check to see if termcolor is installed, we need it for color to xwork
|
||||
try:
|
||||
from termcolor import colored
|
||||
except ImportError:
|
||||
print("termcolor is not installed! Please install termcolor with" '\n', '\n', "pip install termcolor", '\n','\n'+"Note: You may need to run pip as root")
|
||||
exit()
|
||||
if debug == 1:
|
||||
print("termcolor is installed!")
|
||||
# If we are on Windows, we need to do a little more to get color to work
|
||||
if platform.system() == 'Windows':
|
||||
import os
|
||||
os.system('color')
|
||||
# ArgSparce
|
||||
parser = argparse.ArgumentParser()
|
||||
parser.add_argument("-s", "--setup", help="Explains how to setup .txt file", action="store_true")
|
||||
parser.add_argument("-c", "--story", type=int, help="Write story count to file")
|
||||
args = parser.parse_args()
|
||||
# convert the integer to a string because pickiness
|
||||
StoryCount = str(args.story)
|
||||
|
||||
#if statements for ArgSparce
|
||||
|
||||
# line 35 fails if args.story reads as "None", so we need to clear that string if it reads as such.
|
||||
if args.story == None:
|
||||
exec('args.story = int(0)')
|
||||
# args.story should now read as 0
|
||||
if args.story > 0:
|
||||
f = open('storyCount.txt', 'w')
|
||||
f.write(StoryCount)
|
||||
f.close()
|
||||
exit()
|
||||
print("Writing", StoryCount, "to txt file!")
|
||||
if args.setup == True:
|
||||
sys.exit("If you want to include your own MadLibs story, you need to do the following:"+'\n')
|
||||
# Linux easter egg
|
||||
if platform.system() == 'Linux':
|
||||
print('Linux master race! XD')
|
||||
# Introduce yourself
|
||||
print (colored("<<madlibs.", 'red')+colored("p", 'yellow')+colored("y", 'blue'), colored("- Written by Caleb Fontenot>>", 'red'), '\n' "Built on July 13, 2019")
|
||||
print("I pull txt files in the directory you place me in for stories!" '\n' '\n' "Run me with the --setup flag for instructions on setting a story up!" '\n')
|
||||
|
||||
# Notify if verbose
|
||||
if debug == 1:
|
||||
print("Debug mode is enabled! Being verbose!", '\n')
|
||||
else:
|
||||
print('\n')
|
||||
# Now on to business!
|
||||
# Load files
|
||||
f = open('storyCount.txt', 'r')
|
||||
StoryCount = f.read()
|
||||
IntStoryCount = int(StoryCount)
|
||||
print("Detected", IntStoryCount, "stories")
|
||||
# Count stories
|
||||
|
||||
# Randomly pick what story we will use
|
||||
story = random.randint(1, IntStoryCount)
|
||||
|
||||
# Alright, let's get the data from stories.txt
|
||||
f = open('stories.txt', 'r')
|
||||
# This pulls the title from stories.txt
|
||||
storyName = f.readline()
|
||||
# This pulls the story from stories.txt
|
||||
storyContent = f.readline()
|
||||
# todo: remove characters from story identifier and make every even number be recognized as a story, and every odd as it's title
|
||||
|
||||
|
||||
# Hacky shenanigans
|
||||
#selectedStoryName = storyName[story - 1]
|
||||
|
||||
# Print current story
|
||||
print("Current story title is", '"'+storyName+'"')
|
||||
re.findall(
|
||||
|
||||
print(storyContent)
|
||||
@ -0,0 +1,4 @@
|
||||
x = 5
|
||||
for x in range(1000):
|
||||
x*5
|
||||
print(x)
|
||||
@ -0,0 +1,4 @@
|
||||
# Sphinx build info version 1
|
||||
# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
|
||||
config: 72ca452eb08562a9e15d01cdfbf2860a
|
||||
tags: 645f666f9bcd5a90fca523b33c5a78b7
|
||||
@ -0,0 +1,175 @@
|
||||
from datetime import tzinfo, timedelta, datetime
|
||||
|
||||
ZERO = timedelta(0)
|
||||
HOUR = timedelta(hours=1)
|
||||
SECOND = timedelta(seconds=1)
|
||||
|
||||
# A class capturing the platform's idea of local time.
|
||||
# (May result in wrong values on historical times in
|
||||
# timezones where UTC offset and/or the DST rules had
|
||||
# changed in the past.)
|
||||
import time as _time
|
||||
|
||||
STDOFFSET = timedelta(seconds = -_time.timezone)
|
||||
if _time.daylight:
|
||||
DSTOFFSET = timedelta(seconds = -_time.altzone)
|
||||
else:
|
||||
DSTOFFSET = STDOFFSET
|
||||
|
||||
DSTDIFF = DSTOFFSET - STDOFFSET
|
||||
|
||||
class LocalTimezone(tzinfo):
|
||||
|
||||
def fromutc(self, dt):
|
||||
assert dt.tzinfo is self
|
||||
stamp = (dt - datetime(1970, 1, 1, tzinfo=self)) // SECOND
|
||||
args = _time.localtime(stamp)[:6]
|
||||
dst_diff = DSTDIFF // SECOND
|
||||
# Detect fold
|
||||
fold = (args == _time.localtime(stamp - dst_diff))
|
||||
return datetime(*args, microsecond=dt.microsecond,
|
||||
tzinfo=self, fold=fold)
|
||||
|
||||
def utcoffset(self, dt):
|
||||
if self._isdst(dt):
|
||||
return DSTOFFSET
|
||||
else:
|
||||
return STDOFFSET
|
||||
|
||||
def dst(self, dt):
|
||||
if self._isdst(dt):
|
||||
return DSTDIFF
|
||||
else:
|
||||
return ZERO
|
||||
|
||||
def tzname(self, dt):
|
||||
return _time.tzname[self._isdst(dt)]
|
||||
|
||||
def _isdst(self, dt):
|
||||
tt = (dt.year, dt.month, dt.day,
|
||||
dt.hour, dt.minute, dt.second,
|
||||
dt.weekday(), 0, 0)
|
||||
stamp = _time.mktime(tt)
|
||||
tt = _time.localtime(stamp)
|
||||
return tt.tm_isdst > 0
|
||||
|
||||
Local = LocalTimezone()
|
||||
|
||||
|
||||
# A complete implementation of current DST rules for major US time zones.
|
||||
|
||||
def first_sunday_on_or_after(dt):
|
||||
days_to_go = 6 - dt.weekday()
|
||||
if days_to_go:
|
||||
dt += timedelta(days_to_go)
|
||||
return dt
|
||||
|
||||
|
||||
# US DST Rules
|
||||
#
|
||||
# This is a simplified (i.e., wrong for a few cases) set of rules for US
|
||||
# DST start and end times. For a complete and up-to-date set of DST rules
|
||||
# and timezone definitions, visit the Olson Database (or try pytz):
|
||||
# http://www.twinsun.com/tz/tz-link.htm
|
||||
# http://sourceforge.net/projects/pytz/ (might not be up-to-date)
|
||||
#
|
||||
# In the US, since 2007, DST starts at 2am (standard time) on the second
|
||||
# Sunday in March, which is the first Sunday on or after Mar 8.
|
||||
DSTSTART_2007 = datetime(1, 3, 8, 2)
|
||||
# and ends at 2am (DST time) on the first Sunday of Nov.
|
||||
DSTEND_2007 = datetime(1, 11, 1, 2)
|
||||
# From 1987 to 2006, DST used to start at 2am (standard time) on the first
|
||||
# Sunday in April and to end at 2am (DST time) on the last
|
||||
# Sunday of October, which is the first Sunday on or after Oct 25.
|
||||
DSTSTART_1987_2006 = datetime(1, 4, 1, 2)
|
||||
DSTEND_1987_2006 = datetime(1, 10, 25, 2)
|
||||
# From 1967 to 1986, DST used to start at 2am (standard time) on the last
|
||||
# Sunday in April (the one on or after April 24) and to end at 2am (DST time)
|
||||
# on the last Sunday of October, which is the first Sunday
|
||||
# on or after Oct 25.
|
||||
DSTSTART_1967_1986 = datetime(1, 4, 24, 2)
|
||||
DSTEND_1967_1986 = DSTEND_1987_2006
|
||||
|
||||
def us_dst_range(year):
|
||||
# Find start and end times for US DST. For years before 1967, return
|
||||
# start = end for no DST.
|
||||
if 2006 < year:
|
||||
dststart, dstend = DSTSTART_2007, DSTEND_2007
|
||||
elif 1986 < year < 2007:
|
||||
dststart, dstend = DSTSTART_1987_2006, DSTEND_1987_2006
|
||||
elif 1966 < year < 1987:
|
||||
dststart, dstend = DSTSTART_1967_1986, DSTEND_1967_1986
|
||||
else:
|
||||
return (datetime(year, 1, 1), ) * 2
|
||||
|
||||
start = first_sunday_on_or_after(dststart.replace(year=year))
|
||||
end = first_sunday_on_or_after(dstend.replace(year=year))
|
||||
return start, end
|
||||
|
||||
|
||||
class USTimeZone(tzinfo):
|
||||
|
||||
def __init__(self, hours, reprname, stdname, dstname):
|
||||
self.stdoffset = timedelta(hours=hours)
|
||||
self.reprname = reprname
|
||||
self.stdname = stdname
|
||||
self.dstname = dstname
|
||||
|
||||
def __repr__(self):
|
||||
return self.reprname
|
||||
|
||||
def tzname(self, dt):
|
||||
if self.dst(dt):
|
||||
return self.dstname
|
||||
else:
|
||||
return self.stdname
|
||||
|
||||
def utcoffset(self, dt):
|
||||
return self.stdoffset + self.dst(dt)
|
||||
|
||||
def dst(self, dt):
|
||||
if dt is None or dt.tzinfo is None:
|
||||
# An exception may be sensible here, in one or both cases.
|
||||
# It depends on how you want to treat them. The default
|
||||
# fromutc() implementation (called by the default astimezone()
|
||||
# implementation) passes a datetime with dt.tzinfo is self.
|
||||
return ZERO
|
||||
assert dt.tzinfo is self
|
||||
start, end = us_dst_range(dt.year)
|
||||
# Can't compare naive to aware objects, so strip the timezone from
|
||||
# dt first.
|
||||
dt = dt.replace(tzinfo=None)
|
||||
if start + HOUR <= dt < end - HOUR:
|
||||
# DST is in effect.
|
||||
return HOUR
|
||||
if end - HOUR <= dt < end:
|
||||
# Fold (an ambiguous hour): use dt.fold to disambiguate.
|
||||
return ZERO if dt.fold else HOUR
|
||||
if start <= dt < start + HOUR:
|
||||
# Gap (a non-existent hour): reverse the fold rule.
|
||||
return HOUR if dt.fold else ZERO
|
||||
# DST is off.
|
||||
return ZERO
|
||||
|
||||
def fromutc(self, dt):
|
||||
assert dt.tzinfo is self
|
||||
start, end = us_dst_range(dt.year)
|
||||
start = start.replace(tzinfo=self)
|
||||
end = end.replace(tzinfo=self)
|
||||
std_time = dt + self.stdoffset
|
||||
dst_time = std_time + HOUR
|
||||
if end <= dst_time < end + HOUR:
|
||||
# Repeated hour
|
||||
return std_time.replace(fold=1)
|
||||
if std_time < start or dst_time >= end:
|
||||
# Standard time
|
||||
return std_time
|
||||
if start <= std_time < end - HOUR:
|
||||
# Daylight saving time
|
||||
return dst_time
|
||||
|
||||
|
||||
Eastern = USTimeZone(-5, "Eastern", "EST", "EDT")
|
||||
Central = USTimeZone(-6, "Central", "CST", "CDT")
|
||||
Mountain = USTimeZone(-7, "Mountain", "MST", "MDT")
|
||||
Pacific = USTimeZone(-8, "Pacific", "PST", "PDT")
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 11 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 48 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 6.3 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 39 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 48 KiB |
@ -0,0 +1,39 @@
|
||||
=====================
|
||||
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!
|
||||
@ -0,0 +1,92 @@
|
||||
.. _reporting-bugs:
|
||||
|
||||
*****************
|
||||
Dealing with 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.
|
||||
|
||||
It can be sometimes faster to fix bugs yourself and contribute patches to
|
||||
Python as it streamlines the process and involves less people. Learn how to
|
||||
:ref:`contribute <contributing-to-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 <https://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.
|
||||
|
||||
.. _contributing-to-python:
|
||||
|
||||
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/
|
||||
@ -0,0 +1,26 @@
|
||||
.. 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
|
||||
buffer.rst
|
||||
objbuffer.rst
|
||||
@ -0,0 +1,71 @@
|
||||
.. 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)
|
||||
|
||||
|
||||
.. 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.
|
||||
|
||||
|
||||
.. 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.
|
||||
|
||||
|
||||
.. c:function:: void PyObject_Del(void *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:var:: PyObject _Py_NoneStruct
|
||||
|
||||
Object which is visible in Python as ``None``. This should only be accessed
|
||||
using the :c:macro:`Py_None` macro, which evaluates to a pointer to this
|
||||
object.
|
||||
|
||||
|
||||
.. seealso::
|
||||
|
||||
:c:func:`PyModule_Create`
|
||||
To allocate and create extension modules.
|
||||
|
||||
@ -0,0 +1,39 @@
|
||||
.. highlightlang:: c
|
||||
|
||||
.. _apiabiversion:
|
||||
|
||||
***********************
|
||||
API and ABI Versioning
|
||||
***********************
|
||||
|
||||
``PY_VERSION_HEX`` is the Python version number encoded in a single integer.
|
||||
|
||||
For example if the ``PY_VERSION_HEX`` is set to ``0x030401a2``, the underlying
|
||||
version information can be found by treating it as a 32 bit number in
|
||||
the following manner:
|
||||
|
||||
+-------+-------------------------+------------------------------------------------+
|
||||
| Bytes | Bits (big endian order) | Meaning |
|
||||
+=======+=========================+================================================+
|
||||
| ``1`` | ``1-8`` | ``PY_MAJOR_VERSION`` (the ``3`` in |
|
||||
| | | ``3.4.1a2``) |
|
||||
+-------+-------------------------+------------------------------------------------+
|
||||
| ``2`` | ``9-16`` | ``PY_MINOR_VERSION`` (the ``4`` in |
|
||||
| | | ``3.4.1a2``) |
|
||||
+-------+-------------------------+------------------------------------------------+
|
||||
| ``3`` | ``17-24`` | ``PY_MICRO_VERSION`` (the ``1`` in |
|
||||
| | | ``3.4.1a2``) |
|
||||
+-------+-------------------------+------------------------------------------------+
|
||||
| ``4`` | ``25-28`` | ``PY_RELEASE_LEVEL`` (``0xA`` for alpha, |
|
||||
| | | ``0xB`` for beta, ``0xC`` for release |
|
||||
| | | candidate and ``0xF`` for final), in this |
|
||||
| | | case it is alpha. |
|
||||
+-------+-------------------------+------------------------------------------------+
|
||||
| | ``29-32`` | ``PY_RELEASE_SERIAL`` (the ``2`` in |
|
||||
| | | ``3.4.1a2``, zero for final releases) |
|
||||
+-------+-------------------------+------------------------------------------------+
|
||||
|
||||
Thus ``3.4.1a2`` is hexversion ``0x030401a2``.
|
||||
|
||||
All the given macros are defined in :source:`Include/patchlevel.h`.
|
||||
|
||||
@ -0,0 +1,676 @@
|
||||
.. 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.
|
||||
|
||||
-----------------
|
||||
Parsing arguments
|
||||
-----------------
|
||||
|
||||
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.
|
||||
|
||||
Strings and buffers
|
||||
-------------------
|
||||
|
||||
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.
|
||||
|
||||
In general, when a format sets a pointer to a buffer, the buffer is
|
||||
managed by the corresponding Python object, and the buffer shares
|
||||
the lifetime of this object. You won't have to release any memory yourself.
|
||||
The only exceptions are ``es``, ``es#``, ``et`` and ``et#``.
|
||||
|
||||
However, when a :c:type:`Py_buffer` structure gets filled, the underlying
|
||||
buffer is locked so that the caller can subsequently use the buffer even
|
||||
inside a :c:type:`Py_BEGIN_ALLOW_THREADS` block without the risk of mutable data
|
||||
being resized or destroyed. As a result, **you have to call**
|
||||
:c:func:`PyBuffer_Release` after you have finished processing the data (or
|
||||
in any early abort case).
|
||||
|
||||
Unless otherwise stated, buffers are not NUL-terminated.
|
||||
|
||||
Some formats require a read-only :term:`bytes-like object`, and set a
|
||||
pointer instead of a buffer structure. They work by checking that
|
||||
the object's :c:member:`PyBufferProcs.bf_releasebuffer` field is *NULL*,
|
||||
which disallows mutable objects such as :class:`bytearray`.
|
||||
|
||||
.. note::
|
||||
|
||||
For all ``#`` variants of formats (``s#``, ``y#``, etc.), the type of
|
||||
the length argument (int or :c:type:`Py_ssize_t`) is controlled by
|
||||
defining the macro :c:macro:`PY_SSIZE_T_CLEAN` before including
|
||||
:file:`Python.h`. If the macro was defined, length is a
|
||||
:c:type:`Py_ssize_t` rather than an :c:type:`int`. This behavior will change
|
||||
in a future Python version to only support :c:type:`Py_ssize_t` and
|
||||
drop :c:type:`int` support. It is best to always define :c:macro:`PY_SSIZE_T_CLEAN`.
|
||||
|
||||
|
||||
``s`` (:class:`str`) [const char \*]
|
||||
Convert a Unicode object to a C pointer to a character string.
|
||||
A pointer to an existing string is stored in the character pointer
|
||||
variable whose address you pass. The C string is NUL-terminated.
|
||||
The Python string must not contain embedded null code points; if it does,
|
||||
a :exc:`ValueError` exception is raised. Unicode objects are converted
|
||||
to C strings using ``'utf-8'`` encoding. If this conversion fails, a
|
||||
:exc:`UnicodeError` is raised.
|
||||
|
||||
.. note::
|
||||
This format does not accept :term:`bytes-like objects
|
||||
<bytes-like object>`. If you want to accept
|
||||
filesystem paths and convert them to C character strings, it is
|
||||
preferable to use the ``O&`` format with :c:func:`PyUnicode_FSConverter`
|
||||
as *converter*.
|
||||
|
||||
.. versionchanged:: 3.5
|
||||
Previously, :exc:`TypeError` was raised when embedded null code points
|
||||
were encountered in the Python string.
|
||||
|
||||
``s*`` (:class:`str` or :term:`bytes-like object`) [Py_buffer]
|
||||
This format accepts Unicode objects as well as bytes-like objects.
|
||||
It fills a :c:type:`Py_buffer` structure provided by the caller.
|
||||
In this case the resulting C string may contain embedded NUL bytes.
|
||||
Unicode objects are converted to C strings using ``'utf-8'`` encoding.
|
||||
|
||||
``s#`` (:class:`str`, read-only :term:`bytes-like object`) [const char \*, int or :c:type:`Py_ssize_t`]
|
||||
Like ``s*``, except that it doesn't accept mutable objects.
|
||||
The result is stored into two C variables,
|
||||
the first one a pointer to a C string, the second one its length.
|
||||
The string may contain embedded null bytes. Unicode objects are converted
|
||||
to C strings using ``'utf-8'`` encoding.
|
||||
|
||||
``z`` (:class:`str` 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*`` (:class:`str`, :term:`bytes-like object` or ``None``) [Py_buffer]
|
||||
Like ``s*``, but the Python object may also be ``None``, in which case the
|
||||
``buf`` member of the :c:type:`Py_buffer` structure is set to *NULL*.
|
||||
|
||||
``z#`` (:class:`str`, read-only :term:`bytes-like object` or ``None``) [const char \*, int]
|
||||
Like ``s#``, but the Python object may also be ``None``, in which case the C
|
||||
pointer is set to *NULL*.
|
||||
|
||||
``y`` (read-only :term:`bytes-like object`) [const char \*]
|
||||
This format converts a bytes-like object to a C pointer to a character
|
||||
string; it does not accept Unicode objects. The bytes buffer must not
|
||||
contain embedded null bytes; if it does, a :exc:`ValueError`
|
||||
exception is raised.
|
||||
|
||||
.. versionchanged:: 3.5
|
||||
Previously, :exc:`TypeError` was raised when embedded null bytes were
|
||||
encountered in the bytes buffer.
|
||||
|
||||
``y*`` (:term:`bytes-like object`) [Py_buffer]
|
||||
This variant on ``s*`` doesn't accept Unicode objects, only
|
||||
bytes-like objects. **This is the recommended way to accept
|
||||
binary data.**
|
||||
|
||||
``y#`` (read-only :term:`bytes-like object`) [const char \*, int]
|
||||
This variant on ``s#`` doesn't accept Unicode objects, only bytes-like
|
||||
objects.
|
||||
|
||||
``S`` (:class:`bytes`) [PyBytesObject \*]
|
||||
Requires that the Python object is a :class:`bytes` object, without
|
||||
attempting any conversion. Raises :exc:`TypeError` if the object is not
|
||||
a bytes object. The C variable may also be declared as :c:type:`PyObject\*`.
|
||||
|
||||
``Y`` (:class:`bytearray`) [PyByteArrayObject \*]
|
||||
Requires that the Python object is a :class:`bytearray` object, without
|
||||
attempting any conversion. Raises :exc:`TypeError` if the object is not
|
||||
a :class:`bytearray` object. The C variable may also be declared as :c:type:`PyObject\*`.
|
||||
|
||||
``u`` (:class:`str`) [const Py_UNICODE \*]
|
||||
Convert a Python Unicode object to a C pointer to a NUL-terminated buffer of
|
||||
Unicode characters. You must pass the address of a :c:type:`Py_UNICODE`
|
||||
pointer variable, which will be filled with the pointer to an existing
|
||||
Unicode buffer. Please note that the width of a :c:type:`Py_UNICODE`
|
||||
character depends on compilation options (it is either 16 or 32 bits).
|
||||
The Python string must not contain embedded null code points; if it does,
|
||||
a :exc:`ValueError` exception is raised.
|
||||
|
||||
.. versionchanged:: 3.5
|
||||
Previously, :exc:`TypeError` was raised when embedded null code points
|
||||
were encountered in the Python string.
|
||||
|
||||
.. deprecated-removed:: 3.3 4.0
|
||||
Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using
|
||||
:c:func:`PyUnicode_AsWideCharString`.
|
||||
|
||||
``u#`` (:class:`str`) [const 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. This variant allows
|
||||
null code points.
|
||||
|
||||
.. deprecated-removed:: 3.3 4.0
|
||||
Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using
|
||||
:c:func:`PyUnicode_AsWideCharString`.
|
||||
|
||||
``Z`` (:class:`str` or ``None``) [const Py_UNICODE \*]
|
||||
Like ``u``, but the Python object may also be ``None``, in which case the
|
||||
:c:type:`Py_UNICODE` pointer is set to *NULL*.
|
||||
|
||||
.. deprecated-removed:: 3.3 4.0
|
||||
Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using
|
||||
:c:func:`PyUnicode_AsWideCharString`.
|
||||
|
||||
``Z#`` (:class:`str` or ``None``) [const Py_UNICODE \*, int]
|
||||
Like ``u#``, but the Python object may also be ``None``, in which case the
|
||||
:c:type:`Py_UNICODE` pointer is set to *NULL*.
|
||||
|
||||
.. deprecated-removed:: 3.3 4.0
|
||||
Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using
|
||||
:c:func:`PyUnicode_AsWideCharString`.
|
||||
|
||||
``U`` (:class:`str`) [PyObject \*]
|
||||
Requires that the Python object is a Unicode object, without attempting
|
||||
any conversion. Raises :exc:`TypeError` if the object is not a Unicode
|
||||
object. The C variable may also be declared as :c:type:`PyObject\*`.
|
||||
|
||||
``w*`` (read-write :term:`bytes-like object`) [Py_buffer]
|
||||
This format accepts any object which implements the read-write buffer
|
||||
interface. It fills a :c:type:`Py_buffer` structure provided by the caller.
|
||||
The buffer may contain embedded null bytes. The caller have to call
|
||||
:c:func:`PyBuffer_Release` when it is done with the buffer.
|
||||
|
||||
``es`` (:class:`str`) [const char \*encoding, char \*\*buffer]
|
||||
This variant on ``s`` is used for encoding 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 ``'utf-8'`` 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`` (:class:`str`, :class:`bytes` or :class:`bytearray`) [const char \*encoding, char \*\*buffer]
|
||||
Same as ``es`` except that byte string objects are passed through without
|
||||
recoding them. Instead, the implementation assumes that the byte string object uses
|
||||
the encoding passed in as parameter.
|
||||
|
||||
``es#`` (:class:`str`) [const char \*encoding, char \*\*buffer, int \*buffer_length]
|
||||
This variant on ``s#`` is used for encoding 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 ``'utf-8'`` 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:`ValueError` will be set.
|
||||
|
||||
In both cases, *\*buffer_length* is set to the length of the encoded data
|
||||
without the trailing NUL byte.
|
||||
|
||||
``et#`` (:class:`str`, :class:`bytes` or :class:`bytearray`) [const char \*encoding, char \*\*buffer, int \*buffer_length]
|
||||
Same as ``es#`` except that byte string objects are passed through without recoding
|
||||
them. Instead, the implementation assumes that the byte string object uses the
|
||||
encoding passed in as parameter.
|
||||
|
||||
Numbers
|
||||
-------
|
||||
|
||||
``b`` (:class:`int`) [unsigned char]
|
||||
Convert a nonnegative Python integer to an unsigned tiny int, stored in a C
|
||||
:c:type:`unsigned char`.
|
||||
|
||||
``B`` (:class:`int`) [unsigned char]
|
||||
Convert a Python integer to a tiny int without overflow checking, stored in a C
|
||||
:c:type:`unsigned char`.
|
||||
|
||||
``h`` (:class:`int`) [short int]
|
||||
Convert a Python integer to a C :c:type:`short int`.
|
||||
|
||||
``H`` (:class:`int`) [unsigned short int]
|
||||
Convert a Python integer to a C :c:type:`unsigned short int`, without overflow
|
||||
checking.
|
||||
|
||||
``i`` (:class:`int`) [int]
|
||||
Convert a Python integer to a plain C :c:type:`int`.
|
||||
|
||||
``I`` (:class:`int`) [unsigned int]
|
||||
Convert a Python integer to a C :c:type:`unsigned int`, without overflow
|
||||
checking.
|
||||
|
||||
``l`` (:class:`int`) [long int]
|
||||
Convert a Python integer to a C :c:type:`long int`.
|
||||
|
||||
``k`` (:class:`int`) [unsigned long]
|
||||
Convert a Python integer to a C :c:type:`unsigned long` without
|
||||
overflow checking.
|
||||
|
||||
``L`` (:class:`int`) [long long]
|
||||
Convert a Python integer to a C :c:type:`long long`.
|
||||
|
||||
``K`` (:class:`int`) [unsigned long long]
|
||||
Convert a Python integer to a C :c:type:`unsigned long long`
|
||||
without overflow checking.
|
||||
|
||||
``n`` (:class:`int`) [Py_ssize_t]
|
||||
Convert a Python integer to a C :c:type:`Py_ssize_t`.
|
||||
|
||||
``c`` (:class:`bytes` or :class:`bytearray` of length 1) [char]
|
||||
Convert a Python byte, represented as a :class:`bytes` or
|
||||
:class:`bytearray` object of length 1, to a C :c:type:`char`.
|
||||
|
||||
.. versionchanged:: 3.3
|
||||
Allow :class:`bytearray` objects.
|
||||
|
||||
``C`` (:class:`str` of length 1) [int]
|
||||
Convert a Python character, represented as a :class:`str` object of
|
||||
length 1, to a C :c:type:`int`.
|
||||
|
||||
``f`` (:class:`float`) [float]
|
||||
Convert a Python floating point number to a C :c:type:`float`.
|
||||
|
||||
``d`` (:class:`float`) [double]
|
||||
Convert a Python floating point number to a C :c:type:`double`.
|
||||
|
||||
``D`` (:class:`complex`) [Py_complex]
|
||||
Convert a Python complex number to a C :c:type:`Py_complex` structure.
|
||||
|
||||
Other objects
|
||||
-------------
|
||||
|
||||
``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_ampersand:
|
||||
|
||||
``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.
|
||||
|
||||
If the *converter* returns ``Py_CLEANUP_SUPPORTED``, it may get called a
|
||||
second time if the argument parsing eventually fails, giving the converter a
|
||||
chance to release any memory that it had already allocated. In this second
|
||||
call, the *object* parameter will be NULL; *address* will have the same value
|
||||
as in the original call.
|
||||
|
||||
.. versionchanged:: 3.1
|
||||
``Py_CLEANUP_SUPPORTED`` was added.
|
||||
|
||||
``p`` (:class:`bool`) [int]
|
||||
Tests the value passed in for truth (a boolean **p**\ redicate) and converts
|
||||
the result to its equivalent C true/false integer value.
|
||||
Sets the int to ``1`` if the expression was true and ``0`` if it was false.
|
||||
This accepts any valid Python value. See :ref:`truth` for more
|
||||
information about how Python tests values for truth.
|
||||
|
||||
.. versionadded:: 3.3
|
||||
|
||||
``(items)`` (:class:`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.
|
||||
|
||||
It is possible to pass "long" integers (integers whose value exceeds the
|
||||
platform's :const:`LONG_MAX`) 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).
|
||||
|
||||
``$``
|
||||
:c:func:`PyArg_ParseTupleAndKeywords` only:
|
||||
Indicates that the remaining arguments in the Python argument list are
|
||||
keyword-only. Currently, all keyword-only arguments must also be optional
|
||||
arguments, so ``|`` must always be specified before ``$`` in the format
|
||||
string.
|
||||
|
||||
.. versionadded:: 3.3
|
||||
|
||||
``:``
|
||||
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.
|
||||
|
||||
API Functions
|
||||
-------------
|
||||
|
||||
.. 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. The *keywords* argument is a
|
||||
*NULL*-terminated array of keyword parameter names. Empty names denote
|
||||
:ref:`positional-only parameters <positional-only_parameter>`.
|
||||
Returns true on success; on failure, it returns false and raises the
|
||||
appropriate exception.
|
||||
|
||||
.. versionchanged:: 3.6
|
||||
Added support for :ref:`positional-only parameters
|
||||
<positional-only_parameter>`.
|
||||
|
||||
|
||||
.. 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_ValidateKeywordArguments(PyObject *)
|
||||
|
||||
Ensure that the keys in the keywords argument dictionary are strings. This
|
||||
is only needed if :c:func:`PyArg_ParseTupleAndKeywords` is not used, since the
|
||||
latter already does this check.
|
||||
|
||||
.. versionadded:: 3.2
|
||||
|
||||
|
||||
.. XXX deprecated, will be removed
|
||||
.. 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, which has been removed in Python 3. 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)
|
||||
|
||||
|
||||
---------------
|
||||
Building values
|
||||
---------------
|
||||
|
||||
.. 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`` (:class:`str` or ``None``) [const char \*]
|
||||
Convert a null-terminated C string to a Python :class:`str` object using ``'utf-8'``
|
||||
encoding. If the C string pointer is *NULL*, ``None`` is used.
|
||||
|
||||
``s#`` (:class:`str` or ``None``) [const char \*, int]
|
||||
Convert a C string and its length to a Python :class:`str` object using ``'utf-8'``
|
||||
encoding. If the C string pointer is *NULL*, the length is ignored and
|
||||
``None`` is returned.
|
||||
|
||||
``y`` (:class:`bytes`) [const char \*]
|
||||
This converts a C string to a Python :class:`bytes` object. If the C
|
||||
string pointer is *NULL*, ``None`` is returned.
|
||||
|
||||
``y#`` (:class:`bytes`) [const char \*, int]
|
||||
This converts a C string and its lengths to a Python object. If the C
|
||||
string pointer is *NULL*, ``None`` is returned.
|
||||
|
||||
``z`` (:class:`str` or ``None``) [const char \*]
|
||||
Same as ``s``.
|
||||
|
||||
``z#`` (:class:`str` or ``None``) [const char \*, int]
|
||||
Same as ``s#``.
|
||||
|
||||
``u`` (:class:`str`) [const wchar_t \*]
|
||||
Convert a null-terminated :c:type:`wchar_t` buffer of Unicode (UTF-16 or UCS-4)
|
||||
data to a Python Unicode object. If the Unicode buffer pointer is *NULL*,
|
||||
``None`` is returned.
|
||||
|
||||
``u#`` (:class:`str`) [const wchar_t \*, int]
|
||||
Convert a Unicode (UTF-16 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.
|
||||
|
||||
``U`` (:class:`str` or ``None``) [const char \*]
|
||||
Same as ``s``.
|
||||
|
||||
``U#`` (:class:`str` or ``None``) [const char \*, int]
|
||||
Same as ``s#``.
|
||||
|
||||
``i`` (:class:`int`) [int]
|
||||
Convert a plain C :c:type:`int` to a Python integer object.
|
||||
|
||||
``b`` (:class:`int`) [char]
|
||||
Convert a plain C :c:type:`char` to a Python integer object.
|
||||
|
||||
``h`` (:class:`int`) [short int]
|
||||
Convert a plain C :c:type:`short int` to a Python integer object.
|
||||
|
||||
``l`` (:class:`int`) [long int]
|
||||
Convert a C :c:type:`long int` to a Python integer object.
|
||||
|
||||
``B`` (:class:`int`) [unsigned char]
|
||||
Convert a C :c:type:`unsigned char` to a Python integer object.
|
||||
|
||||
``H`` (:class:`int`) [unsigned short int]
|
||||
Convert a C :c:type:`unsigned short int` to a Python integer object.
|
||||
|
||||
``I`` (:class:`int`) [unsigned int]
|
||||
Convert a C :c:type:`unsigned int` to a Python integer object.
|
||||
|
||||
``k`` (:class:`int`) [unsigned long]
|
||||
Convert a C :c:type:`unsigned long` to a Python integer object.
|
||||
|
||||
``L`` (:class:`int`) [long long]
|
||||
Convert a C :c:type:`long long` to a Python integer object.
|
||||
|
||||
``K`` (:class:`int`) [unsigned long long]
|
||||
Convert a C :c:type:`unsigned long long` to a Python integer object.
|
||||
|
||||
``n`` (:class:`int`) [Py_ssize_t]
|
||||
Convert a C :c:type:`Py_ssize_t` to a Python integer.
|
||||
|
||||
``c`` (:class:`bytes` of length 1) [char]
|
||||
Convert a C :c:type:`int` representing a byte to a Python :class:`bytes` object of
|
||||
length 1.
|
||||
|
||||
``C`` (:class:`str` of length 1) [int]
|
||||
Convert a C :c:type:`int` representing a character to Python :class:`str`
|
||||
object of length 1.
|
||||
|
||||
``d`` (:class:`float`) [double]
|
||||
Convert a C :c:type:`double` to a Python floating point number.
|
||||
|
||||
``f`` (:class:`float`) [float]
|
||||
Convert a C :c:type:`float` to a Python floating point number.
|
||||
|
||||
``D`` (:class:`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)`` (:class:`tuple`) [*matching-items*]
|
||||
Convert a sequence of C values to a Python tuple with the same number of items.
|
||||
|
||||
``[items]`` (:class:`list`) [*matching-items*]
|
||||
Convert a sequence of C values to a Python list with the same number of items.
|
||||
|
||||
``{items}`` (:class:`dict`) [*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.
|
||||
@ -0,0 +1,46 @@
|
||||
.. 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`.
|
||||
|
||||
|
||||
.. 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.
|
||||
|
||||
|
||||
.. c:macro:: Py_RETURN_TRUE
|
||||
|
||||
Return :const:`Py_True` from a function, properly incrementing its reference
|
||||
count.
|
||||
|
||||
|
||||
.. 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*.
|
||||
@ -0,0 +1,508 @@
|
||||
.. highlightlang:: c
|
||||
|
||||
.. index::
|
||||
single: buffer protocol
|
||||
single: buffer interface; (see buffer protocol)
|
||||
single: buffer object; (see buffer protocol)
|
||||
|
||||
.. _bufferobjects:
|
||||
|
||||
Buffer Protocol
|
||||
---------------
|
||||
|
||||
.. sectionauthor:: Greg Stein <gstein@lyra.org>
|
||||
.. sectionauthor:: Benjamin Peterson
|
||||
.. sectionauthor:: Stefan Krah
|
||||
|
||||
|
||||
Certain objects available in Python wrap access to an underlying memory
|
||||
array or *buffer*. Such objects include the built-in :class:`bytes` and
|
||||
:class:`bytearray`, and some extension types like :class:`array.array`.
|
||||
Third-party libraries may define their own types for special purposes, such
|
||||
as image processing or numeric analysis.
|
||||
|
||||
While each of these types have their own semantics, they share the common
|
||||
characteristic of being backed by a possibly large memory buffer. It is
|
||||
then desirable, in some situations, to access that buffer directly and
|
||||
without intermediate copying.
|
||||
|
||||
Python provides such a facility at the C level in the form of the :ref:`buffer
|
||||
protocol <bufferobjects>`. This protocol has two sides:
|
||||
|
||||
.. index:: single: PyBufferProcs
|
||||
|
||||
- on the producer side, a type can export a "buffer interface" which allows
|
||||
objects of that type to expose information about their underlying buffer.
|
||||
This interface is described in the section :ref:`buffer-structs`;
|
||||
|
||||
- on the consumer side, several means are available to obtain a pointer to
|
||||
the raw underlying data of an object (for example a method parameter).
|
||||
|
||||
Simple objects such as :class:`bytes` and :class:`bytearray` expose their
|
||||
underlying buffer in byte-oriented form. Other forms are possible; for example,
|
||||
the elements exposed by an :class:`array.array` can be multi-byte values.
|
||||
|
||||
An example consumer of the buffer interface is the :meth:`~io.BufferedIOBase.write`
|
||||
method of file objects: any object that can export a series of bytes through
|
||||
the buffer interface can be written to a file. While :meth:`write` only
|
||||
needs read-only access to the internal contents of the object passed to it,
|
||||
other methods such as :meth:`~io.BufferedIOBase.readinto` need write access
|
||||
to the contents of their argument. The buffer interface allows objects to
|
||||
selectively allow or reject exporting of read-write and read-only buffers.
|
||||
|
||||
There are two ways for a consumer of the buffer interface to acquire a buffer
|
||||
over a target object:
|
||||
|
||||
* call :c:func:`PyObject_GetBuffer` with the right parameters;
|
||||
|
||||
* call :c:func:`PyArg_ParseTuple` (or one of its siblings) with one of the
|
||||
``y*``, ``w*`` or ``s*`` :ref:`format codes <arg-parsing>`.
|
||||
|
||||
In both cases, :c:func:`PyBuffer_Release` must be called when the buffer
|
||||
isn't needed anymore. Failure to do so could lead to various issues such as
|
||||
resource leaks.
|
||||
|
||||
|
||||
.. _buffer-structure:
|
||||
|
||||
Buffer structure
|
||||
================
|
||||
|
||||
Buffer structures (or simply "buffers") are useful as a way to expose the
|
||||
binary data from another object 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.
|
||||
|
||||
Contrary to most data types exposed by the Python interpreter, buffers
|
||||
are not :c:type:`PyObject` pointers but rather simple C structures. This
|
||||
allows them to be created and copied very simply. When a generic wrapper
|
||||
around a buffer is needed, a :ref:`memoryview <memoryview-objects>` object
|
||||
can be created.
|
||||
|
||||
For short instructions how to write an exporting object, see
|
||||
:ref:`Buffer Object Structures <buffer-structs>`. For obtaining
|
||||
a buffer, see :c:func:`PyObject_GetBuffer`.
|
||||
|
||||
.. c:type:: Py_buffer
|
||||
|
||||
.. c:member:: void \*buf
|
||||
|
||||
A pointer to the start of the logical structure described by the buffer
|
||||
fields. This can be any location within the underlying physical memory
|
||||
block of the exporter. For example, with negative :c:member:`~Py_buffer.strides`
|
||||
the value may point to the end of the memory block.
|
||||
|
||||
For :term:`contiguous` arrays, the value points to the beginning of
|
||||
the memory block.
|
||||
|
||||
.. c:member:: void \*obj
|
||||
|
||||
A new reference to the exporting object. The reference is owned by
|
||||
the consumer and automatically decremented and set to *NULL* by
|
||||
:c:func:`PyBuffer_Release`. The field is the equivalent of the return
|
||||
value of any standard C-API function.
|
||||
|
||||
As a special case, for *temporary* buffers that are wrapped by
|
||||
:c:func:`PyMemoryView_FromBuffer` or :c:func:`PyBuffer_FillInfo`
|
||||
this field is *NULL*. In general, exporting objects MUST NOT
|
||||
use this scheme.
|
||||
|
||||
.. c:member:: Py_ssize_t len
|
||||
|
||||
``product(shape) * itemsize``. For contiguous arrays, this is the length
|
||||
of the underlying memory block. For non-contiguous arrays, it is the length
|
||||
that the logical structure would have if it were copied to a contiguous
|
||||
representation.
|
||||
|
||||
Accessing ``((char *)buf)[0] up to ((char *)buf)[len-1]`` is only valid
|
||||
if the buffer has been obtained by a request that guarantees contiguity. In
|
||||
most cases such a request will be :c:macro:`PyBUF_SIMPLE` or :c:macro:`PyBUF_WRITABLE`.
|
||||
|
||||
.. c:member:: int readonly
|
||||
|
||||
An indicator of whether the buffer is read-only. This field is controlled
|
||||
by the :c:macro:`PyBUF_WRITABLE` flag.
|
||||
|
||||
.. c:member:: Py_ssize_t itemsize
|
||||
|
||||
Item size in bytes of a single element. Same as the value of :func:`struct.calcsize`
|
||||
called on non-NULL :c:member:`~Py_buffer.format` values.
|
||||
|
||||
Important exception: If a consumer requests a buffer without the
|
||||
:c:macro:`PyBUF_FORMAT` flag, :c:member:`~Py_buffer.format` will
|
||||
be set to *NULL*, but :c:member:`~Py_buffer.itemsize` still has
|
||||
the value for the original format.
|
||||
|
||||
If :c:member:`~Py_buffer.shape` is present, the equality
|
||||
``product(shape) * itemsize == len`` still holds and the consumer
|
||||
can use :c:member:`~Py_buffer.itemsize` to navigate the buffer.
|
||||
|
||||
If :c:member:`~Py_buffer.shape` is *NULL* as a result of a :c:macro:`PyBUF_SIMPLE`
|
||||
or a :c:macro:`PyBUF_WRITABLE` request, the consumer must disregard
|
||||
:c:member:`~Py_buffer.itemsize` and assume ``itemsize == 1``.
|
||||
|
||||
.. c:member:: const char \*format
|
||||
|
||||
A *NUL* terminated string in :mod:`struct` module style syntax describing
|
||||
the contents of a single item. If this is *NULL*, ``"B"`` (unsigned bytes)
|
||||
is assumed.
|
||||
|
||||
This field is controlled by the :c:macro:`PyBUF_FORMAT` flag.
|
||||
|
||||
.. c:member:: int ndim
|
||||
|
||||
The number of dimensions the memory represents as an n-dimensional array.
|
||||
If it is ``0``, :c:member:`~Py_buffer.buf` points to a single item representing
|
||||
a scalar. In this case, :c:member:`~Py_buffer.shape`, :c:member:`~Py_buffer.strides`
|
||||
and :c:member:`~Py_buffer.suboffsets` MUST be *NULL*.
|
||||
|
||||
The macro :c:macro:`PyBUF_MAX_NDIM` limits the maximum number of dimensions
|
||||
to 64. Exporters MUST respect this limit, consumers of multi-dimensional
|
||||
buffers SHOULD be able to handle up to :c:macro:`PyBUF_MAX_NDIM` dimensions.
|
||||
|
||||
.. c:member:: Py_ssize_t \*shape
|
||||
|
||||
An array of :c:type:`Py_ssize_t` of length :c:member:`~Py_buffer.ndim`
|
||||
indicating the shape of the memory as an n-dimensional array. Note that
|
||||
``shape[0] * ... * shape[ndim-1] * itemsize`` MUST be equal to
|
||||
:c:member:`~Py_buffer.len`.
|
||||
|
||||
Shape values are restricted to ``shape[n] >= 0``. The case
|
||||
``shape[n] == 0`` requires special attention. See `complex arrays`_
|
||||
for further information.
|
||||
|
||||
The shape array is read-only for the consumer.
|
||||
|
||||
.. c:member:: Py_ssize_t \*strides
|
||||
|
||||
An array of :c:type:`Py_ssize_t` of length :c:member:`~Py_buffer.ndim`
|
||||
giving the number of bytes to skip to get to a new element in each
|
||||
dimension.
|
||||
|
||||
Stride values can be any integer. For regular arrays, strides are
|
||||
usually positive, but a consumer MUST be able to handle the case
|
||||
``strides[n] <= 0``. See `complex arrays`_ for further information.
|
||||
|
||||
The strides array is read-only for the consumer.
|
||||
|
||||
.. c:member:: Py_ssize_t \*suboffsets
|
||||
|
||||
An array of :c:type:`Py_ssize_t` of length :c:member:`~Py_buffer.ndim`.
|
||||
If ``suboffsets[n] >= 0``, the values stored along the nth dimension are
|
||||
pointers and the suboffset value dictates how many bytes to add to each
|
||||
pointer after de-referencing. A suboffset value that is 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).
|
||||
|
||||
This type of array representation is used by the Python Imaging Library
|
||||
(PIL). See `complex arrays`_ for further information how to access elements
|
||||
of such an array.
|
||||
|
||||
The suboffsets array is read-only for the consumer.
|
||||
|
||||
.. 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 MUST NOT alter this
|
||||
value.
|
||||
|
||||
.. _buffer-request-types:
|
||||
|
||||
Buffer request types
|
||||
====================
|
||||
|
||||
Buffers are usually obtained by sending a buffer request to an exporting
|
||||
object via :c:func:`PyObject_GetBuffer`. Since the complexity of the logical
|
||||
structure of the memory can vary drastically, the consumer uses the *flags*
|
||||
argument to specify the exact buffer type it can handle.
|
||||
|
||||
All :c:data:`Py_buffer` fields are unambiguously defined by the request
|
||||
type.
|
||||
|
||||
request-independent fields
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
The following fields are not influenced by *flags* and must always be filled in
|
||||
with the correct values: :c:member:`~Py_buffer.obj`, :c:member:`~Py_buffer.buf`,
|
||||
:c:member:`~Py_buffer.len`, :c:member:`~Py_buffer.itemsize`, :c:member:`~Py_buffer.ndim`.
|
||||
|
||||
|
||||
readonly, format
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
.. c:macro:: PyBUF_WRITABLE
|
||||
|
||||
Controls the :c:member:`~Py_buffer.readonly` field. If set, the exporter
|
||||
MUST provide a writable buffer or else report failure. Otherwise, the
|
||||
exporter MAY provide either a read-only or writable buffer, but the choice
|
||||
MUST be consistent for all consumers.
|
||||
|
||||
.. c:macro:: PyBUF_FORMAT
|
||||
|
||||
Controls the :c:member:`~Py_buffer.format` field. If set, this field MUST
|
||||
be filled in correctly. Otherwise, this field MUST be *NULL*.
|
||||
|
||||
|
||||
:c:macro:`PyBUF_WRITABLE` can be \|'d to any of the flags in the next section.
|
||||
Since :c:macro:`PyBUF_SIMPLE` is defined as 0, :c:macro:`PyBUF_WRITABLE`
|
||||
can be used as a stand-alone flag to request a simple writable buffer.
|
||||
|
||||
:c:macro:`PyBUF_FORMAT` can be \|'d to any of the flags except :c:macro:`PyBUF_SIMPLE`.
|
||||
The latter already implies format ``B`` (unsigned bytes).
|
||||
|
||||
|
||||
shape, strides, suboffsets
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The flags that control the logical structure of the memory are listed
|
||||
in decreasing order of complexity. Note that each flag contains all bits
|
||||
of the flags below it.
|
||||
|
||||
.. tabularcolumns:: |p{0.35\linewidth}|l|l|l|
|
||||
|
||||
+-----------------------------+-------+---------+------------+
|
||||
| Request | shape | strides | suboffsets |
|
||||
+=============================+=======+=========+============+
|
||||
| .. c:macro:: PyBUF_INDIRECT | yes | yes | if needed |
|
||||
+-----------------------------+-------+---------+------------+
|
||||
| .. c:macro:: PyBUF_STRIDES | yes | yes | NULL |
|
||||
+-----------------------------+-------+---------+------------+
|
||||
| .. c:macro:: PyBUF_ND | yes | NULL | NULL |
|
||||
+-----------------------------+-------+---------+------------+
|
||||
| .. c:macro:: PyBUF_SIMPLE | NULL | NULL | NULL |
|
||||
+-----------------------------+-------+---------+------------+
|
||||
|
||||
|
||||
.. index:: contiguous, C-contiguous, Fortran contiguous
|
||||
|
||||
contiguity requests
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
C or Fortran :term:`contiguity <contiguous>` can be explicitly requested,
|
||||
with and without stride information. Without stride information, the buffer
|
||||
must be C-contiguous.
|
||||
|
||||
.. tabularcolumns:: |p{0.35\linewidth}|l|l|l|l|
|
||||
|
||||
+-----------------------------------+-------+---------+------------+--------+
|
||||
| Request | shape | strides | suboffsets | contig |
|
||||
+===================================+=======+=========+============+========+
|
||||
| .. c:macro:: PyBUF_C_CONTIGUOUS | yes | yes | NULL | C |
|
||||
+-----------------------------------+-------+---------+------------+--------+
|
||||
| .. c:macro:: PyBUF_F_CONTIGUOUS | yes | yes | NULL | F |
|
||||
+-----------------------------------+-------+---------+------------+--------+
|
||||
| .. c:macro:: PyBUF_ANY_CONTIGUOUS | yes | yes | NULL | C or F |
|
||||
+-----------------------------------+-------+---------+------------+--------+
|
||||
| .. c:macro:: PyBUF_ND | yes | NULL | NULL | C |
|
||||
+-----------------------------------+-------+---------+------------+--------+
|
||||
|
||||
|
||||
compound requests
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
All possible requests are fully defined by some combination of the flags in
|
||||
the previous section. For convenience, the buffer protocol provides frequently
|
||||
used combinations as single flags.
|
||||
|
||||
In the following table *U* stands for undefined contiguity. The consumer would
|
||||
have to call :c:func:`PyBuffer_IsContiguous` to determine contiguity.
|
||||
|
||||
.. tabularcolumns:: |p{0.35\linewidth}|l|l|l|l|l|l|
|
||||
|
||||
+-------------------------------+-------+---------+------------+--------+----------+--------+
|
||||
| Request | shape | strides | suboffsets | contig | readonly | format |
|
||||
+===============================+=======+=========+============+========+==========+========+
|
||||
| .. c:macro:: PyBUF_FULL | yes | yes | if needed | U | 0 | yes |
|
||||
+-------------------------------+-------+---------+------------+--------+----------+--------+
|
||||
| .. c:macro:: PyBUF_FULL_RO | yes | yes | if needed | U | 1 or 0 | yes |
|
||||
+-------------------------------+-------+---------+------------+--------+----------+--------+
|
||||
| .. c:macro:: PyBUF_RECORDS | yes | yes | NULL | U | 0 | yes |
|
||||
+-------------------------------+-------+---------+------------+--------+----------+--------+
|
||||
| .. c:macro:: PyBUF_RECORDS_RO | yes | yes | NULL | U | 1 or 0 | yes |
|
||||
+-------------------------------+-------+---------+------------+--------+----------+--------+
|
||||
| .. c:macro:: PyBUF_STRIDED | yes | yes | NULL | U | 0 | NULL |
|
||||
+-------------------------------+-------+---------+------------+--------+----------+--------+
|
||||
| .. c:macro:: PyBUF_STRIDED_RO | yes | yes | NULL | U | 1 or 0 | NULL |
|
||||
+-------------------------------+-------+---------+------------+--------+----------+--------+
|
||||
| .. c:macro:: PyBUF_CONTIG | yes | NULL | NULL | C | 0 | NULL |
|
||||
+-------------------------------+-------+---------+------------+--------+----------+--------+
|
||||
| .. c:macro:: PyBUF_CONTIG_RO | yes | NULL | NULL | C | 1 or 0 | NULL |
|
||||
+-------------------------------+-------+---------+------------+--------+----------+--------+
|
||||
|
||||
|
||||
Complex arrays
|
||||
==============
|
||||
|
||||
NumPy-style: shape and strides
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The logical structure of NumPy-style arrays is defined by :c:member:`~Py_buffer.itemsize`,
|
||||
:c:member:`~Py_buffer.ndim`, :c:member:`~Py_buffer.shape` and :c:member:`~Py_buffer.strides`.
|
||||
|
||||
If ``ndim == 0``, the memory location pointed to by :c:member:`~Py_buffer.buf` is
|
||||
interpreted as a scalar of size :c:member:`~Py_buffer.itemsize`. In that case,
|
||||
both :c:member:`~Py_buffer.shape` and :c:member:`~Py_buffer.strides` are *NULL*.
|
||||
|
||||
If :c:member:`~Py_buffer.strides` is *NULL*, the array is interpreted as
|
||||
a standard n-dimensional C-array. Otherwise, the consumer must access an
|
||||
n-dimensional array as follows:
|
||||
|
||||
``ptr = (char *)buf + indices[0] * strides[0] + ... + indices[n-1] * strides[n-1]``
|
||||
``item = *((typeof(item) *)ptr);``
|
||||
|
||||
|
||||
As noted above, :c:member:`~Py_buffer.buf` can point to any location within
|
||||
the actual memory block. An exporter can check the validity of a buffer with
|
||||
this function:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
def verify_structure(memlen, itemsize, ndim, shape, strides, offset):
|
||||
"""Verify that the parameters represent a valid array within
|
||||
the bounds of the allocated memory:
|
||||
char *mem: start of the physical memory block
|
||||
memlen: length of the physical memory block
|
||||
offset: (char *)buf - mem
|
||||
"""
|
||||
if offset % itemsize:
|
||||
return False
|
||||
if offset < 0 or offset+itemsize > memlen:
|
||||
return False
|
||||
if any(v % itemsize for v in strides):
|
||||
return False
|
||||
|
||||
if ndim <= 0:
|
||||
return ndim == 0 and not shape and not strides
|
||||
if 0 in shape:
|
||||
return True
|
||||
|
||||
imin = sum(strides[j]*(shape[j]-1) for j in range(ndim)
|
||||
if strides[j] <= 0)
|
||||
imax = sum(strides[j]*(shape[j]-1) for j in range(ndim)
|
||||
if strides[j] > 0)
|
||||
|
||||
return 0 <= offset+imin and offset+imax+itemsize <= memlen
|
||||
|
||||
|
||||
PIL-style: shape, strides and suboffsets
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
In addition to the regular items, PIL-style arrays can contain pointers
|
||||
that must be followed in order to get to the next element in a dimension.
|
||||
For example, the regular three-dimensional C-array ``char v[2][2][3]`` can
|
||||
also be viewed as an array of 2 pointers to 2 two-dimensional arrays:
|
||||
``char (*v[2])[2][3]``. In suboffsets representation, those two pointers
|
||||
can be embedded at the start of :c:member:`~Py_buffer.buf`, pointing
|
||||
to two ``char x[2][3]`` arrays that can be located anywhere in memory.
|
||||
|
||||
|
||||
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;
|
||||
}
|
||||
|
||||
|
||||
Buffer-related functions
|
||||
========================
|
||||
|
||||
.. c:function:: int PyObject_CheckBuffer(PyObject *obj)
|
||||
|
||||
Return ``1`` if *obj* supports the buffer interface otherwise ``0``. When ``1`` is
|
||||
returned, it doesn't guarantee that :c:func:`PyObject_GetBuffer` will
|
||||
succeed. This function always succeeds.
|
||||
|
||||
|
||||
.. c:function:: int PyObject_GetBuffer(PyObject *exporter, Py_buffer *view, int flags)
|
||||
|
||||
Send a request to *exporter* to fill in *view* as specified by *flags*.
|
||||
If the exporter cannot provide a buffer of the exact type, it MUST raise
|
||||
:c:data:`PyExc_BufferError`, set :c:member:`view->obj` to *NULL* and
|
||||
return ``-1``.
|
||||
|
||||
On success, fill in *view*, set :c:member:`view->obj` to a new reference
|
||||
to *exporter* and return 0. In the case of chained buffer providers
|
||||
that redirect requests to a single object, :c:member:`view->obj` MAY
|
||||
refer to this object instead of *exporter* (See :ref:`Buffer Object Structures <buffer-structs>`).
|
||||
|
||||
Successful calls to :c:func:`PyObject_GetBuffer` must be paired with calls
|
||||
to :c:func:`PyBuffer_Release`, similar to :c:func:`malloc` and :c:func:`free`.
|
||||
Thus, after the consumer is done with the buffer, :c:func:`PyBuffer_Release`
|
||||
must be called exactly once.
|
||||
|
||||
|
||||
.. c:function:: void PyBuffer_Release(Py_buffer *view)
|
||||
|
||||
Release the buffer *view* and decrement the reference count for
|
||||
:c:member:`view->obj`. This function MUST be called when the buffer
|
||||
is no longer being used, otherwise reference leaks may occur.
|
||||
|
||||
It is an error to call this function on a buffer that was not obtained via
|
||||
:c:func:`PyObject_GetBuffer`.
|
||||
|
||||
|
||||
.. c:function:: Py_ssize_t PyBuffer_SizeFromFormat(const char *)
|
||||
|
||||
Return the implied :c:data:`~Py_buffer.itemsize` from :c:data:`~Py_buffer.format`.
|
||||
This function is not yet implemented.
|
||||
|
||||
|
||||
.. c:function:: int PyBuffer_IsContiguous(Py_buffer *view, char order)
|
||||
|
||||
Return ``1`` if the memory defined by the *view* is C-style (*order* is
|
||||
``'C'``) or Fortran-style (*order* is ``'F'``) :term:`contiguous` or either one
|
||||
(*order* is ``'A'``). Return ``0`` otherwise. This function always succeeds.
|
||||
|
||||
|
||||
.. c:function:: int PyBuffer_ToContiguous(void *buf, Py_buffer *src, Py_ssize_t len, char order)
|
||||
|
||||
Copy *len* bytes from *src* to its contiguous representation in *buf*.
|
||||
*order* can be ``'C'`` or ``'F'`` (for C-style or Fortran-style ordering).
|
||||
``0`` is returned on success, ``-1`` on error.
|
||||
|
||||
This function fails if *len* != *src->len*.
|
||||
|
||||
|
||||
.. c:function:: void PyBuffer_FillContiguousStrides(int ndims, Py_ssize_t *shape, Py_ssize_t *strides, int itemsize, char order)
|
||||
|
||||
Fill the *strides* array with byte-strides of a :term:`contiguous` (C-style if
|
||||
*order* is ``'C'`` or Fortran-style if *order* is ``'F'``) array of the
|
||||
given shape with the given number of bytes per element.
|
||||
|
||||
|
||||
.. c:function:: int PyBuffer_FillInfo(Py_buffer *view, PyObject *exporter, void *buf, Py_ssize_t len, int readonly, int flags)
|
||||
|
||||
Handle buffer requests for an exporter that wants to expose *buf* of size *len*
|
||||
with writability set according to *readonly*. *buf* is interpreted as a sequence
|
||||
of unsigned bytes.
|
||||
|
||||
The *flags* argument indicates the request type. This function always fills in
|
||||
*view* as specified by flags, unless *buf* has been designated as read-only
|
||||
and :c:macro:`PyBUF_WRITABLE` is set in *flags*.
|
||||
|
||||
On success, set :c:member:`view->obj` to a new reference to *exporter* and
|
||||
return 0. Otherwise, raise :c:data:`PyExc_BufferError`, set
|
||||
:c:member:`view->obj` to *NULL* and return ``-1``;
|
||||
|
||||
If this function is used as part of a :ref:`getbufferproc <buffer-structs>`,
|
||||
*exporter* MUST be set to the exporting object and *flags* must be passed
|
||||
unmodified. Otherwise, *exporter* MUST be NULL.
|
||||
@ -0,0 +1,87 @@
|
||||
.. highlightlang:: c
|
||||
|
||||
.. _bytearrayobjects:
|
||||
|
||||
Byte Array Objects
|
||||
------------------
|
||||
|
||||
.. index:: object: bytearray
|
||||
|
||||
|
||||
.. 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 :class:`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
|
||||
:ref:`buffer protocol <bufferobjects>`.
|
||||
|
||||
.. 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. The returned array always has an extra
|
||||
null byte appended.
|
||||
|
||||
|
||||
.. 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`.
|
||||
@ -0,0 +1,205 @@
|
||||
.. highlightlang:: c
|
||||
|
||||
.. _bytesobjects:
|
||||
|
||||
Bytes Objects
|
||||
-------------
|
||||
|
||||
These functions raise :exc:`TypeError` when expecting a bytes parameter and are
|
||||
called with a non-bytes parameter.
|
||||
|
||||
.. index:: object: bytes
|
||||
|
||||
|
||||
.. c:type:: PyBytesObject
|
||||
|
||||
This subtype of :c:type:`PyObject` represents a Python bytes object.
|
||||
|
||||
|
||||
.. c:var:: PyTypeObject PyBytes_Type
|
||||
|
||||
This instance of :c:type:`PyTypeObject` represents the Python bytes type; it
|
||||
is the same object as :class:`bytes` in the Python layer.
|
||||
|
||||
|
||||
.. c:function:: int PyBytes_Check(PyObject *o)
|
||||
|
||||
Return true if the object *o* is a bytes object or an instance of a subtype
|
||||
of the bytes type.
|
||||
|
||||
|
||||
.. c:function:: int PyBytes_CheckExact(PyObject *o)
|
||||
|
||||
Return true if the object *o* is a bytes object, but not an instance of a
|
||||
subtype of the bytes type.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyBytes_FromString(const char *v)
|
||||
|
||||
Return a new bytes 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* PyBytes_FromStringAndSize(const char *v, Py_ssize_t len)
|
||||
|
||||
Return a new bytes 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 bytes object are uninitialized.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyBytes_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 bytes object and return
|
||||
a bytes object 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:
|
||||
|
||||
.. % XXX: This should be exactly the same as the table in PyErr_Format.
|
||||
.. % One should just refer to the other.
|
||||
.. % XXX: 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 byte, |
|
||||
| | | represented as a C int. |
|
||||
+-------------------+---------------+--------------------------------+
|
||||
| :attr:`%d` | int | Equivalent to |
|
||||
| | | ``printf("%d")``. [1]_ |
|
||||
+-------------------+---------------+--------------------------------+
|
||||
| :attr:`%u` | unsigned int | Equivalent to |
|
||||
| | | ``printf("%u")``. [1]_ |
|
||||
+-------------------+---------------+--------------------------------+
|
||||
| :attr:`%ld` | long | Equivalent to |
|
||||
| | | ``printf("%ld")``. [1]_ |
|
||||
+-------------------+---------------+--------------------------------+
|
||||
| :attr:`%lu` | unsigned long | Equivalent to |
|
||||
| | | ``printf("%lu")``. [1]_ |
|
||||
+-------------------+---------------+--------------------------------+
|
||||
| :attr:`%zd` | Py_ssize_t | Equivalent to |
|
||||
| | | ``printf("%zd")``. [1]_ |
|
||||
+-------------------+---------------+--------------------------------+
|
||||
| :attr:`%zu` | size_t | Equivalent to |
|
||||
| | | ``printf("%zu")``. [1]_ |
|
||||
+-------------------+---------------+--------------------------------+
|
||||
| :attr:`%i` | int | Equivalent to |
|
||||
| | | ``printf("%i")``. [1]_ |
|
||||
+-------------------+---------------+--------------------------------+
|
||||
| :attr:`%x` | int | Equivalent to |
|
||||
| | | ``printf("%x")``. [1]_ |
|
||||
+-------------------+---------------+--------------------------------+
|
||||
| :attr:`%s` | const char\* | A null-terminated C character |
|
||||
| | | array. |
|
||||
+-------------------+---------------+--------------------------------+
|
||||
| :attr:`%p` | const 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 object, and any extra arguments discarded.
|
||||
|
||||
.. [1] For integer specifiers (d, u, ld, lu, zd, zu, i, x): the 0-conversion
|
||||
flag has effect even when a precision is given.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyBytes_FromFormatV(const char *format, va_list vargs)
|
||||
|
||||
Identical to :c:func:`PyBytes_FromFormat` except that it takes exactly two
|
||||
arguments.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyBytes_FromObject(PyObject *o)
|
||||
|
||||
Return the bytes representation of object *o* that implements the buffer
|
||||
protocol.
|
||||
|
||||
|
||||
.. c:function:: Py_ssize_t PyBytes_Size(PyObject *o)
|
||||
|
||||
Return the length of the bytes in bytes object *o*.
|
||||
|
||||
|
||||
.. c:function:: Py_ssize_t PyBytes_GET_SIZE(PyObject *o)
|
||||
|
||||
Macro form of :c:func:`PyBytes_Size` but without error checking.
|
||||
|
||||
|
||||
.. c:function:: char* PyBytes_AsString(PyObject *o)
|
||||
|
||||
Return a pointer to the contents of *o*. The pointer
|
||||
refers to the internal buffer of *o*, which consists of ``len(o) + 1``
|
||||
bytes. The last byte in the buffer is always null, regardless of
|
||||
whether there are any other null bytes. The data must not be
|
||||
modified in any way, unless the object was just created using
|
||||
``PyBytes_FromStringAndSize(NULL, size)``. It must not be deallocated. If
|
||||
*o* is not a bytes object at all, :c:func:`PyBytes_AsString` returns *NULL*
|
||||
and raises :exc:`TypeError`.
|
||||
|
||||
|
||||
.. c:function:: char* PyBytes_AS_STRING(PyObject *string)
|
||||
|
||||
Macro form of :c:func:`PyBytes_AsString` but without error checking.
|
||||
|
||||
|
||||
.. c:function:: int PyBytes_AsStringAndSize(PyObject *obj, char **buffer, Py_ssize_t *length)
|
||||
|
||||
Return the null-terminated contents of the object *obj*
|
||||
through the output variables *buffer* and *length*.
|
||||
|
||||
If *length* is *NULL*, the bytes object
|
||||
may not contain embedded null bytes;
|
||||
if it does, the function returns ``-1`` and a :exc:`ValueError` is raised.
|
||||
|
||||
The buffer refers to an internal buffer of *obj*, which includes an
|
||||
additional null byte at the end (not counted in *length*). The data
|
||||
must not be modified in any way, unless the object was just created using
|
||||
``PyBytes_FromStringAndSize(NULL, size)``. It must not be deallocated. If
|
||||
*obj* is not a bytes object at all, :c:func:`PyBytes_AsStringAndSize`
|
||||
returns ``-1`` and raises :exc:`TypeError`.
|
||||
|
||||
.. versionchanged:: 3.5
|
||||
Previously, :exc:`TypeError` was raised when embedded null bytes were
|
||||
encountered in the bytes object.
|
||||
|
||||
|
||||
.. c:function:: void PyBytes_Concat(PyObject **bytes, PyObject *newpart)
|
||||
|
||||
Create a new bytes object in *\*bytes* containing the contents of *newpart*
|
||||
appended to *bytes*; the caller will own the new reference. The reference to
|
||||
the old value of *bytes* will be stolen. If the new object cannot be
|
||||
created, the old reference to *bytes* will still be discarded and the value
|
||||
of *\*bytes* will be set to *NULL*; the appropriate exception will be set.
|
||||
|
||||
|
||||
.. c:function:: void PyBytes_ConcatAndDel(PyObject **bytes, PyObject *newpart)
|
||||
|
||||
Create a new bytes object in *\*bytes* containing the contents of *newpart*
|
||||
appended to *bytes*. This version decrements the reference count of
|
||||
*newpart*.
|
||||
|
||||
|
||||
.. c:function:: int _PyBytes_Resize(PyObject **bytes, Py_ssize_t newsize)
|
||||
|
||||
A way to resize a bytes object even though it is "immutable". Only use this
|
||||
to build up a brand new bytes object; don't use this if the bytes may already
|
||||
be known in other parts of the code. It is an error to call this function if
|
||||
the refcount on the input bytes object is not one. Pass the address of an
|
||||
existing bytes object as an lvalue (it may be written into), and the new size
|
||||
desired. On success, *\*bytes* holds the resized bytes object and ``0`` is
|
||||
returned; the address in *\*bytes* may differ from its input value. If the
|
||||
reallocation fails, the original bytes object at *\*bytes* is deallocated,
|
||||
*\*bytes* is set to *NULL*, :exc:`MemoryError` is set, and ``-1`` is
|
||||
returned.
|
||||
@ -0,0 +1,157 @@
|
||||
.. highlightlang:: c
|
||||
|
||||
.. _capsules:
|
||||
|
||||
Capsules
|
||||
--------
|
||||
|
||||
.. index:: object: Capsule
|
||||
|
||||
Refer to :ref:`using-capsules` for more information on using these objects.
|
||||
|
||||
.. versionadded:: 3.1
|
||||
|
||||
|
||||
.. 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.
|
||||
@ -0,0 +1,62 @@
|
||||
.. 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.
|
||||
@ -0,0 +1,48 @@
|
||||
.. 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(PyCodeObject *co)
|
||||
|
||||
Return the number of free variables in *co*.
|
||||
|
||||
.. c:function:: PyCodeObject* PyCode_New(int argcount, int kwonlyargcount, 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:: PyCodeObject* 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
|
||||
:func:`exec` or :func:`eval` the resulting code object.
|
||||
@ -0,0 +1,123 @@
|
||||
.. _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*. This function always succeeds.
|
||||
|
||||
.. 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``).
|
||||
|
||||
.. c:function:: PyObject* PyCodec_NameReplaceErrors(PyObject *exc)
|
||||
|
||||
Replace the unicode encode error with ``\N{...}`` escapes.
|
||||
|
||||
.. versionadded:: 3.5
|
||||
@ -0,0 +1,132 @@
|
||||
.. 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 :class:`complex` in the Python layer.
|
||||
|
||||
|
||||
.. c:function:: int PyComplex_Check(PyObject *p)
|
||||
|
||||
Return true if its argument is a :c:type:`PyComplexObject` or a subtype of
|
||||
:c:type:`PyComplexObject`.
|
||||
|
||||
|
||||
.. 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`.
|
||||
|
||||
|
||||
.. 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*.
|
||||
|
||||
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. Upon failure, this method returns ``-1.0`` as a real value.
|
||||
@ -0,0 +1,117 @@
|
||||
.. 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::
|
||||
|
||||
long.rst
|
||||
bool.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.
|
||||
|
||||
.. XXX sort out unicode, str, bytes and bytearray
|
||||
|
||||
.. toctree::
|
||||
|
||||
bytes.rst
|
||||
bytearray.rst
|
||||
unicode.rst
|
||||
tuple.rst
|
||||
list.rst
|
||||
|
||||
|
||||
.. _mapobjects:
|
||||
|
||||
Container Objects
|
||||
=================
|
||||
|
||||
.. index:: object: mapping
|
||||
|
||||
.. toctree::
|
||||
|
||||
dict.rst
|
||||
set.rst
|
||||
|
||||
|
||||
.. _otherobjects:
|
||||
|
||||
Function Objects
|
||||
================
|
||||
|
||||
.. toctree::
|
||||
|
||||
function.rst
|
||||
method.rst
|
||||
cell.rst
|
||||
code.rst
|
||||
|
||||
|
||||
Other Objects
|
||||
=============
|
||||
|
||||
.. toctree::
|
||||
|
||||
file.rst
|
||||
module.rst
|
||||
iterator.rst
|
||||
descriptor.rst
|
||||
slice.rst
|
||||
memoryview.rst
|
||||
weakref.rst
|
||||
capsule.rst
|
||||
gen.rst
|
||||
coro.rst
|
||||
contextvars.rst
|
||||
datetime.rst
|
||||
@ -0,0 +1,144 @@
|
||||
.. highlightlang:: c
|
||||
|
||||
.. _contextvarsobjects:
|
||||
|
||||
Context Variables Objects
|
||||
-------------------------
|
||||
|
||||
.. _contextvarsobjects_pointertype_change:
|
||||
.. versionchanged:: 3.7.1
|
||||
|
||||
.. note::
|
||||
|
||||
In Python 3.7.1 the signatures of all context variables
|
||||
C APIs were **changed** to use :c:type:`PyObject` pointers instead
|
||||
of :c:type:`PyContext`, :c:type:`PyContextVar`, and
|
||||
:c:type:`PyContextToken`, e.g.::
|
||||
|
||||
// in 3.7.0:
|
||||
PyContext *PyContext_New(void);
|
||||
|
||||
// in 3.7.1+:
|
||||
PyObject *PyContext_New(void);
|
||||
|
||||
See :issue:`34762` for more details.
|
||||
|
||||
|
||||
.. versionadded:: 3.7
|
||||
|
||||
This section details the public C API for the :mod:`contextvars` module.
|
||||
|
||||
.. c:type:: PyContext
|
||||
|
||||
The C structure used to represent a :class:`contextvars.Context`
|
||||
object.
|
||||
|
||||
.. c:type:: PyContextVar
|
||||
|
||||
The C structure used to represent a :class:`contextvars.ContextVar`
|
||||
object.
|
||||
|
||||
.. c:type:: PyContextToken
|
||||
|
||||
The C structure used to represent a :class:`contextvars.Token` object.
|
||||
|
||||
.. c:var:: PyTypeObject PyContext_Type
|
||||
|
||||
The type object representing the *context* type.
|
||||
|
||||
.. c:var:: PyTypeObject PyContextVar_Type
|
||||
|
||||
The type object representing the *context variable* type.
|
||||
|
||||
.. c:var:: PyTypeObject PyContextToken_Type
|
||||
|
||||
The type object representing the *context variable token* type.
|
||||
|
||||
|
||||
Type-check macros:
|
||||
|
||||
.. c:function:: int PyContext_CheckExact(PyObject *o)
|
||||
|
||||
Return true if *o* is of type :c:data:`PyContext_Type`. *o* must not be
|
||||
*NULL*. This function always succeeds.
|
||||
|
||||
.. c:function:: int PyContextVar_CheckExact(PyObject *o)
|
||||
|
||||
Return true if *o* is of type :c:data:`PyContextVar_Type`. *o* must not be
|
||||
*NULL*. This function always succeeds.
|
||||
|
||||
.. c:function:: int PyContextToken_CheckExact(PyObject *o)
|
||||
|
||||
Return true if *o* is of type :c:data:`PyContextToken_Type`.
|
||||
*o* must not be *NULL*. This function always succeeds.
|
||||
|
||||
|
||||
Context object management functions:
|
||||
|
||||
.. c:function:: PyObject *PyContext_New(void)
|
||||
|
||||
Create a new empty context object. Returns ``NULL`` if an error
|
||||
has occurred.
|
||||
|
||||
.. c:function:: PyObject *PyContext_Copy(PyObject *ctx)
|
||||
|
||||
Create a shallow copy of the passed *ctx* context object.
|
||||
Returns ``NULL`` if an error has occurred.
|
||||
|
||||
.. c:function:: PyObject *PyContext_CopyCurrent(void)
|
||||
|
||||
Create a shallow copy of the current thread context.
|
||||
Returns ``NULL`` if an error has occurred.
|
||||
|
||||
.. c:function:: int PyContext_Enter(PyObject *ctx)
|
||||
|
||||
Set *ctx* as the current context for the current thread.
|
||||
Returns ``0`` on success, and ``-1`` on error.
|
||||
|
||||
.. c:function:: int PyContext_Exit(PyObject *ctx)
|
||||
|
||||
Deactivate the *ctx* context and restore the previous context as the
|
||||
current context for the current thread. Returns ``0`` on success,
|
||||
and ``-1`` on error.
|
||||
|
||||
.. c:function:: int PyContext_ClearFreeList()
|
||||
|
||||
Clear the context variable free list. Return the total number of
|
||||
freed items. This function always succeeds.
|
||||
|
||||
|
||||
Context variable functions:
|
||||
|
||||
.. c:function:: PyObject *PyContextVar_New(const char *name, PyObject *def)
|
||||
|
||||
Create a new ``ContextVar`` object. The *name* parameter is used
|
||||
for introspection and debug purposes. The *def* parameter may optionally
|
||||
specify the default value for the context variable. If an error has
|
||||
occurred, this function returns ``NULL``.
|
||||
|
||||
.. c:function:: int PyContextVar_Get(PyObject *var, PyObject *default_value, PyObject **value)
|
||||
|
||||
Get the value of a context variable. Returns ``-1`` if an error has
|
||||
occurred during lookup, and ``0`` if no error occurred, whether or not
|
||||
a value was found.
|
||||
|
||||
If the context variable was found, *value* will be a pointer to it.
|
||||
If the context variable was *not* found, *value* will point to:
|
||||
|
||||
- *default_value*, if not ``NULL``;
|
||||
- the default value of *var*, if not ``NULL``;
|
||||
- ``NULL``
|
||||
|
||||
If the value was found, the function will create a new reference to it.
|
||||
|
||||
.. c:function:: PyObject *PyContextVar_Set(PyObject *var, PyObject *value)
|
||||
|
||||
Set the value of *var* to *value* in the current context. Returns a
|
||||
pointer to a :c:type:`PyObject` object, or ``NULL`` if an error
|
||||
has occurred.
|
||||
|
||||
.. c:function:: int PyContextVar_Reset(PyObject *var, PyObject *token)
|
||||
|
||||
Reset the state of the *var* context variable to that it was in before
|
||||
:c:func:`PyContextVar_Set` that returned the *token* was called.
|
||||
This function returns ``0`` on success and ``-1`` on error.
|
||||
@ -0,0 +1,131 @@
|
||||
.. 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
|
||||
:exc:`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:: 3.1
|
||||
|
||||
|
||||
.. 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:: 3.1
|
||||
|
||||
|
||||
.. c:function:: int PyOS_stricmp(const char *s1, const char *s2)
|
||||
|
||||
Case insensitive comparison of strings. The function works almost
|
||||
identically to :c:func:`strcmp` except that it ignores the case.
|
||||
|
||||
|
||||
.. c:function:: int PyOS_strnicmp(const char *s1, const 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.
|
||||
@ -0,0 +1,34 @@
|
||||
.. highlightlang:: c
|
||||
|
||||
.. _coro-objects:
|
||||
|
||||
Coroutine Objects
|
||||
-----------------
|
||||
|
||||
.. versionadded:: 3.5
|
||||
|
||||
Coroutine objects are what functions declared with an ``async`` keyword
|
||||
return.
|
||||
|
||||
|
||||
.. c:type:: PyCoroObject
|
||||
|
||||
The C structure used for coroutine objects.
|
||||
|
||||
|
||||
.. c:var:: PyTypeObject PyCoro_Type
|
||||
|
||||
The type object corresponding to coroutine objects.
|
||||
|
||||
|
||||
.. c:function:: int PyCoro_CheckExact(PyObject *ob)
|
||||
|
||||
Return true if *ob*'s type is *PyCoro_Type*; *ob* must not be *NULL*.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyCoro_New(PyFrameObject *frame, PyObject *name, PyObject *qualname)
|
||||
|
||||
Create and return a new coroutine object based on the *frame* object,
|
||||
with ``__name__`` and ``__qualname__`` set to *name* and *qualname*.
|
||||
A reference to *frame* is stolen by this function. The *frame* argument
|
||||
must not be *NULL*.
|
||||
@ -0,0 +1,249 @@
|
||||
.. 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.
|
||||
|
||||
Macro for access to the UTC singleton:
|
||||
|
||||
.. c:var:: PyObject* PyDateTime_TimeZone_UTC
|
||||
|
||||
Returns the time zone singleton representing UTC, the same object as
|
||||
:attr:`datetime.timezone.utc`.
|
||||
|
||||
.. versionadded:: 3.7
|
||||
|
||||
|
||||
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*.
|
||||
|
||||
|
||||
.. c:function:: int PyDate_CheckExact(PyObject *ob)
|
||||
|
||||
Return true if *ob* is of type :c:data:`PyDateTime_DateType`. *ob* must not be
|
||||
*NULL*.
|
||||
|
||||
|
||||
.. 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*.
|
||||
|
||||
|
||||
.. c:function:: int PyDateTime_CheckExact(PyObject *ob)
|
||||
|
||||
Return true if *ob* is of type :c:data:`PyDateTime_DateTimeType`. *ob* must not
|
||||
be *NULL*.
|
||||
|
||||
|
||||
.. 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*.
|
||||
|
||||
|
||||
.. c:function:: int PyTime_CheckExact(PyObject *ob)
|
||||
|
||||
Return true if *ob* is of type :c:data:`PyDateTime_TimeType`. *ob* must not be
|
||||
*NULL*.
|
||||
|
||||
|
||||
.. 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*.
|
||||
|
||||
|
||||
.. c:function:: int PyDelta_CheckExact(PyObject *ob)
|
||||
|
||||
Return true if *ob* is of type :c:data:`PyDateTime_DeltaType`. *ob* must not be
|
||||
*NULL*.
|
||||
|
||||
|
||||
.. 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*.
|
||||
|
||||
|
||||
.. c:function:: int PyTZInfo_CheckExact(PyObject *ob)
|
||||
|
||||
Return true if *ob* is of type :c:data:`PyDateTime_TZInfoType`. *ob* must not be
|
||||
*NULL*.
|
||||
|
||||
|
||||
Macros to create objects:
|
||||
|
||||
.. c:function:: PyObject* PyDate_FromDate(int year, int month, int day)
|
||||
|
||||
Return a :class:`datetime.date` object with the specified year, month and day.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyDateTime_FromDateAndTime(int year, int month, int day, int hour, int minute, int second, int usecond)
|
||||
|
||||
Return a :class:`datetime.datetime` object with the specified year, month, day, hour,
|
||||
minute, second and microsecond.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyDateTime_FromDateAndTimeAndFold(int year, int month, int day, int hour, int minute, int second, int usecond, int fold)
|
||||
|
||||
Return a :class:`datetime.datetime` object with the specified year, month, day, hour,
|
||||
minute, second, microsecond and fold.
|
||||
|
||||
.. versionadded:: 3.6
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyTime_FromTime(int hour, int minute, int second, int usecond)
|
||||
|
||||
Return a :class:`datetime.time` object with the specified hour, minute, second and
|
||||
microsecond.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyTime_FromTimeAndFold(int hour, int minute, int second, int usecond, int fold)
|
||||
|
||||
Return a :class:`datetime.time` object with the specified hour, minute, second,
|
||||
microsecond and fold.
|
||||
|
||||
.. versionadded:: 3.6
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyDelta_FromDSU(int days, int seconds, int useconds)
|
||||
|
||||
Return a :class:`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
|
||||
:class:`datetime.timedelta` objects.
|
||||
|
||||
.. c:function:: PyObject* PyTimeZone_FromOffset(PyDateTime_DeltaType* offset)
|
||||
|
||||
Return a :class:`datetime.timezone` object with an unnamed fixed offset
|
||||
represented by the *offset* argument.
|
||||
|
||||
.. versionadded:: 3.7
|
||||
|
||||
.. c:function:: PyObject* PyTimeZone_FromOffsetAndName(PyDateTime_DeltaType* offset, PyUnicode* name)
|
||||
|
||||
Return a :class:`datetime.timezone` object with a fixed offset represented
|
||||
by the *offset* argument and with tzname *name*.
|
||||
|
||||
.. versionadded:: 3.7
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
.. c:function:: int PyDateTime_GET_MONTH(PyDateTime_Date *o)
|
||||
|
||||
Return the month, as an int from 1 through 12.
|
||||
|
||||
|
||||
.. c:function:: int PyDateTime_GET_DAY(PyDateTime_Date *o)
|
||||
|
||||
Return the day, as an int from 1 through 31.
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
.. c:function:: int PyDateTime_DATE_GET_MINUTE(PyDateTime_DateTime *o)
|
||||
|
||||
Return the minute, as an int from 0 through 59.
|
||||
|
||||
|
||||
.. c:function:: int PyDateTime_DATE_GET_SECOND(PyDateTime_DateTime *o)
|
||||
|
||||
Return the second, as an int from 0 through 59.
|
||||
|
||||
|
||||
.. c:function:: int PyDateTime_DATE_GET_MICROSECOND(PyDateTime_DateTime *o)
|
||||
|
||||
Return the microsecond, as an int from 0 through 999999.
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
.. c:function:: int PyDateTime_TIME_GET_MINUTE(PyDateTime_Time *o)
|
||||
|
||||
Return the minute, as an int from 0 through 59.
|
||||
|
||||
|
||||
.. c:function:: int PyDateTime_TIME_GET_SECOND(PyDateTime_Time *o)
|
||||
|
||||
Return the second, as an int from 0 through 59.
|
||||
|
||||
|
||||
.. c:function:: int PyDateTime_TIME_GET_MICROSECOND(PyDateTime_Time *o)
|
||||
|
||||
Return the microsecond, as an int from 0 through 999999.
|
||||
|
||||
|
||||
Macros to extract fields from time delta objects. The argument must be an
|
||||
instance of :c:data:`PyDateTime_Delta`, including subclasses. The argument must
|
||||
not be *NULL*, and the type is not checked:
|
||||
|
||||
.. c:function:: int PyDateTime_DELTA_GET_DAYS(PyDateTime_Delta *o)
|
||||
|
||||
Return the number of days, as an int from -999999999 to 999999999.
|
||||
|
||||
.. versionadded:: 3.3
|
||||
|
||||
|
||||
.. c:function:: int PyDateTime_DELTA_GET_SECONDS(PyDateTime_Delta *o)
|
||||
|
||||
Return the number of seconds, as an int from 0 through 86399.
|
||||
|
||||
.. versionadded:: 3.3
|
||||
|
||||
|
||||
.. c:function:: int PyDateTime_DELTA_GET_MICROSECONDS(PyDateTime_Delta *o)
|
||||
|
||||
Return the number of microseconds, as an int from 0 through 999999.
|
||||
|
||||
.. versionadded:: 3.3
|
||||
|
||||
|
||||
Macros for the convenience of modules implementing the DB API:
|
||||
|
||||
.. c:function:: PyObject* PyDateTime_FromTimestamp(PyObject *args)
|
||||
|
||||
Create and return a new :class:`datetime.datetime` object given an argument
|
||||
tuple suitable for passing to :meth:`datetime.datetime.fromtimestamp()`.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyDate_FromTimestamp(PyObject *args)
|
||||
|
||||
Create and return a new :class:`datetime.date` object given an argument
|
||||
tuple suitable for passing to :meth:`datetime.date.fromtimestamp()`.
|
||||
@ -0,0 +1,40 @@
|
||||
.. 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.
|
||||
|
||||
.. XXX document these!
|
||||
|
||||
.. c:var:: PyTypeObject PyProperty_Type
|
||||
|
||||
The type object for the built-in descriptor types.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyDescr_NewGetSet(PyTypeObject *type, struct PyGetSetDef *getset)
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyDescr_NewMember(PyTypeObject *type, struct PyMemberDef *meth)
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyDescr_NewMethod(PyTypeObject *type, struct PyMethodDef *meth)
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyDescr_NewWrapper(PyTypeObject *type, struct wrapperbase *wrapper, void *wrapped)
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyDescr_NewClassMethod(PyTypeObject *type, PyMethodDef *method)
|
||||
|
||||
|
||||
.. 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.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyWrapper_New(PyObject *, PyObject *)
|
||||
@ -0,0 +1,240 @@
|
||||
.. 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
|
||||
|
||||
This instance of :c:type:`PyTypeObject` represents the Python dictionary
|
||||
type. This is the same object as :class:`dict` in the Python layer.
|
||||
|
||||
|
||||
.. 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.
|
||||
|
||||
|
||||
.. 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.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyDict_New()
|
||||
|
||||
Return a new empty dictionary, or *NULL* on failure.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyDictProxy_New(PyObject *mapping)
|
||||
|
||||
Return a :class:`types.MappingProxyType` object for a mapping which
|
||||
enforces read-only behavior. This is normally used to create a view to
|
||||
prevent modification of the dictionary for non-dynamic class types.
|
||||
|
||||
|
||||
.. 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``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyDict_Copy(PyObject *p)
|
||||
|
||||
Return a new dictionary that contains the same key-value pairs as *p*.
|
||||
|
||||
|
||||
.. 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: PyUnicode_FromString()
|
||||
|
||||
Insert *value* into the dictionary *p* using *key* as a key. *key* should
|
||||
be a :c:type:`const char\*`. The key object is created using
|
||||
``PyUnicode_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, const 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.
|
||||
|
||||
Note that exceptions which occur while calling :meth:`__hash__` and
|
||||
:meth:`__eq__` methods will get suppressed.
|
||||
To get error reporting use :c:func:`PyDict_GetItemWithError()` instead.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyDict_GetItemWithError(PyObject *p, PyObject *key)
|
||||
|
||||
Variant of :c:func:`PyDict_GetItem` that does not suppress
|
||||
exceptions. Return *NULL* **with** an exception set if an exception
|
||||
occurred. Return *NULL* **without** an exception set if the key
|
||||
wasn't present.
|
||||
|
||||
|
||||
.. 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:`const char\*`, rather than a :c:type:`PyObject\*`.
|
||||
|
||||
Note that exceptions which occur while calling :meth:`__hash__` and
|
||||
:meth:`__eq__` methods and creating a temporary string object
|
||||
will get suppressed.
|
||||
To get error reporting use :c:func:`PyDict_GetItemWithError()` instead.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyDict_SetDefault(PyObject *p, PyObject *key, PyObject *defaultobj)
|
||||
|
||||
This is the same as the Python-level :meth:`dict.setdefault`. If present, it
|
||||
returns the value corresponding to *key* from the dictionary *p*. If the key
|
||||
is not in the dict, it is inserted with value *defaultobj* and *defaultobj*
|
||||
is returned. This function evaluates the hash function of *key* only once,
|
||||
instead of evaluating it independently for the lookup and the insertion.
|
||||
|
||||
.. versionadded:: 3.4
|
||||
|
||||
.. c:function:: PyObject* PyDict_Items(PyObject *p)
|
||||
|
||||
Return a :c:type:`PyListObject` containing all the items from the dictionary.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyDict_Keys(PyObject *p)
|
||||
|
||||
Return a :c:type:`PyListObject` containing all the keys from the dictionary.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyDict_Values(PyObject *p)
|
||||
|
||||
Return a :c:type:`PyListObject` containing all the values from the dictionary
|
||||
*p*.
|
||||
|
||||
|
||||
.. 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.
|
||||
|
||||
|
||||
.. 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 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)) {
|
||||
long i = PyLong_AsLong(value);
|
||||
if (i == -1 && PyErr_Occurred()) {
|
||||
return -1;
|
||||
}
|
||||
PyObject *o = PyLong_FromLong(i + 1);
|
||||
if (o == NULL)
|
||||
return -1;
|
||||
if (PyDict_SetItem(self->dict, key, o) < 0) {
|
||||
Py_DECREF(o);
|
||||
return -1;
|
||||
}
|
||||
Py_DECREF(o);
|
||||
}
|
||||
|
||||
|
||||
.. 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.
|
||||
|
||||
|
||||
.. 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.
|
||||
|
||||
|
||||
.. 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
|
||||
|
||||
|
||||
.. c:function:: int PyDict_ClearFreeList()
|
||||
|
||||
Clear the free list. Return the total number of freed items.
|
||||
|
||||
.. versionadded:: 3.3
|
||||
File diff suppressed because it is too large
Load Diff
@ -0,0 +1,76 @@
|
||||
.. highlightlang:: c
|
||||
|
||||
.. _fileobjects:
|
||||
|
||||
File Objects
|
||||
------------
|
||||
|
||||
.. index:: object: file
|
||||
|
||||
These APIs are a minimal emulation of the Python 2 C API for built-in file
|
||||
objects, which used to rely on the buffered I/O (:c:type:`FILE\*`) support
|
||||
from the C standard library. In Python 3, files and streams use the new
|
||||
:mod:`io` module, which defines several layers over the low-level unbuffered
|
||||
I/O of the operating system. The functions described below are
|
||||
convenience C wrappers over these new APIs, and meant mostly for internal
|
||||
error reporting in the interpreter; third-party code is advised to access
|
||||
the :mod:`io` APIs instead.
|
||||
|
||||
|
||||
.. c:function:: PyFile_FromFd(int fd, const char *name, const char *mode, int buffering, const char *encoding, const char *errors, const char *newline, int closefd)
|
||||
|
||||
Create a Python file object from the file descriptor of an already
|
||||
opened file *fd*. The arguments *name*, *encoding*, *errors* and *newline*
|
||||
can be *NULL* to use the defaults; *buffering* can be *-1* to use the
|
||||
default. *name* is ignored and kept for backward compatibility. Return
|
||||
*NULL* on failure. For a more comprehensive description of the arguments,
|
||||
please refer to the :func:`io.open` function documentation.
|
||||
|
||||
.. warning::
|
||||
|
||||
Since Python streams have their own buffering layer, mixing them with
|
||||
OS-level file descriptors can produce various issues (such as unexpected
|
||||
ordering of data).
|
||||
|
||||
.. versionchanged:: 3.2
|
||||
Ignore *name* attribute.
|
||||
|
||||
|
||||
.. c:function:: int PyObject_AsFileDescriptor(PyObject *p)
|
||||
|
||||
Return the file descriptor associated with *p* as an :c:type:`int`. If the
|
||||
object is an integer, its value is returned. If not, the
|
||||
object's :meth:`~io.IOBase.fileno` method is called if it exists; the
|
||||
method must return an integer, which is returned as the file descriptor
|
||||
value. Sets an exception and returns ``-1`` on failure.
|
||||
|
||||
|
||||
.. 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:: 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.
|
||||
@ -0,0 +1,79 @@
|
||||
.. 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
|
||||
|
||||
This instance of :c:type:`PyTypeObject` represents the Python floating point
|
||||
type. This is the same object as :class:`float` in the Python layer.
|
||||
|
||||
|
||||
.. c:function:: int PyFloat_Check(PyObject *p)
|
||||
|
||||
Return true if its argument is a :c:type:`PyFloatObject` or a subtype of
|
||||
:c:type:`PyFloatObject`.
|
||||
|
||||
|
||||
.. 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`.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyFloat_FromString(PyObject *str)
|
||||
|
||||
Create a :c:type:`PyFloatObject` object based on the string value in *str*, or
|
||||
*NULL* on failure.
|
||||
|
||||
|
||||
.. 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`.
|
||||
|
||||
|
||||
.. c:function:: double PyFloat_GetMax()
|
||||
|
||||
Return the maximum representable finite float *DBL_MAX* as C :c:type:`double`.
|
||||
|
||||
|
||||
.. c:function:: double PyFloat_GetMin()
|
||||
|
||||
Return the minimum normalized positive float *DBL_MIN* as C :c:type:`double`.
|
||||
|
||||
.. c:function:: int PyFloat_ClearFreeList()
|
||||
|
||||
Clear the float free list. Return the number of items that could not
|
||||
be freed.
|
||||
@ -0,0 +1,108 @@
|
||||
.. 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 and name are retrieved from the code object. *__module__*
|
||||
is retrieved from *globals*. The argument defaults, annotations and closure are
|
||||
set to *NULL*. *__qualname__* is set to the same value as the function's name.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyFunction_NewWithQualName(PyObject *code, PyObject *globals, PyObject *qualname)
|
||||
|
||||
As :c:func:`PyFunction_New`, but also allows setting the function object's
|
||||
``__qualname__`` attribute. *qualname* should be a unicode object or NULL;
|
||||
if NULL, the ``__qualname__`` attribute is set to the same value as its
|
||||
``__name__`` attribute.
|
||||
|
||||
.. versionadded:: 3.3
|
||||
|
||||
|
||||
.. 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.
|
||||
|
||||
|
||||
.. c:function:: PyObject *PyFunction_GetAnnotations(PyObject *op)
|
||||
|
||||
Return the annotations of the function object *op*. This can be a
|
||||
mutable dictionary or *NULL*.
|
||||
|
||||
|
||||
.. c:function:: int PyFunction_SetAnnotations(PyObject *op, PyObject *annotations)
|
||||
|
||||
Set the annotations for the function object *op*. *annotations*
|
||||
must be a dictionary or *Py_None*.
|
||||
|
||||
Raises :exc:`SystemError` and returns ``-1`` on failure.
|
||||
@ -0,0 +1,159 @@
|
||||
.. 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.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
.. 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.
|
||||
|
||||
|
||||
.. 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.
|
||||
|
||||
.. deprecated:: 3.6
|
||||
This macro is removed from Python 3.8.
|
||||
|
||||
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.
|
||||
|
||||
.. deprecated:: 3.6
|
||||
This macro is removed from Python 3.8.
|
||||
|
||||
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;
|
||||
}
|
||||
|
||||
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.
|
||||
@ -0,0 +1,44 @@
|
||||
.. 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` or :c:func:`PyGen_NewWithQualName`.
|
||||
|
||||
|
||||
.. 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(PyObject *ob)
|
||||
|
||||
Return true if *ob* is a generator object; *ob* must not be *NULL*.
|
||||
|
||||
|
||||
.. c:function:: int PyGen_CheckExact(PyObject *ob)
|
||||
|
||||
Return true if *ob*'s type is *PyGen_Type*; *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 argument must not be
|
||||
*NULL*.
|
||||
|
||||
.. c:function:: PyObject* PyGen_NewWithQualName(PyFrameObject *frame, PyObject *name, PyObject *qualname)
|
||||
|
||||
Create and return a new generator object based on the *frame* object,
|
||||
with ``__name__`` and ``__qualname__`` set to *name* and *qualname*.
|
||||
A reference to *frame* is stolen by this function. The *frame* argument
|
||||
must not be *NULL*.
|
||||
@ -0,0 +1,317 @@
|
||||
.. 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. A failing
|
||||
import of a module doesn't leave the module in :data:`sys.modules`.
|
||||
|
||||
This function always uses absolute imports.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyImport_ImportModuleNoBlock(const char *name)
|
||||
|
||||
This function is a deprecated alias of :c:func:`PyImport_ImportModule`.
|
||||
|
||||
.. versionchanged:: 3.3
|
||||
This function used to fail immediately when the import lock was held
|
||||
by another thread. In Python 3.3 though, the locking scheme switched
|
||||
to per-module locks for most purposes, so this function's special
|
||||
behaviour isn't needed anymore.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyImport_ImportModuleEx(const 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__`.
|
||||
|
||||
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.
|
||||
|
||||
Failing imports remove incomplete module objects, like with
|
||||
:c:func:`PyImport_ImportModule`.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyImport_ImportModuleLevelObject(PyObject *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:: 3.3
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyImport_ImportModuleLevel(const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)
|
||||
|
||||
Similar to :c:func:`PyImport_ImportModuleLevelObject`, but the name is a
|
||||
UTF-8 encoded string instead of a Unicode object.
|
||||
|
||||
.. versionchanged:: 3.3
|
||||
Negative values for *level* are no longer accepted.
|
||||
|
||||
.. c:function:: PyObject* PyImport_Import(PyObject *name)
|
||||
|
||||
This is a higher-level interface that calls the current "import hook
|
||||
function" (with an explicit *level* of 0, meaning absolute import). 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.
|
||||
|
||||
This function always uses absolute imports.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyImport_ReloadModule(PyObject *m)
|
||||
|
||||
Reload a module. 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_AddModuleObject(PyObject *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.
|
||||
|
||||
.. versionadded:: 3.3
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyImport_AddModule(const char *name)
|
||||
|
||||
Similar to :c:func:`PyImport_AddModuleObject`, but the name is a UTF-8
|
||||
encoded string instead of a Unicode object.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyImport_ExecCodeModule(const 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. *name*
|
||||
is removed from :attr:`sys.modules` in error cases, 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:`__spec__` and :attr:`__loader__` will be set, if
|
||||
not set already, with the appropriate values. The spec's loader will
|
||||
be set to the module's ``__loader__`` (if set) and to an instance of
|
||||
:class:`SourceFileLoader` otherwise.
|
||||
|
||||
The module's :attr:`__file__` attribute will be set to the code object's
|
||||
:c:member:`co_filename`. If applicable, :attr:`__cached__` will also
|
||||
be set.
|
||||
|
||||
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.
|
||||
|
||||
See also :c:func:`PyImport_ExecCodeModuleEx` and
|
||||
:c:func:`PyImport_ExecCodeModuleWithPathnames`.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyImport_ExecCodeModuleEx(const char *name, PyObject *co, const 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``.
|
||||
|
||||
See also :c:func:`PyImport_ExecCodeModuleWithPathnames`.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyImport_ExecCodeModuleObject(PyObject *name, PyObject *co, PyObject *pathname, PyObject *cpathname)
|
||||
|
||||
Like :c:func:`PyImport_ExecCodeModuleEx`, but the :attr:`__cached__`
|
||||
attribute of the module object is set to *cpathname* if it is
|
||||
non-``NULL``. Of the three functions, this is the preferred one to use.
|
||||
|
||||
.. versionadded:: 3.3
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyImport_ExecCodeModuleWithPathnames(const char *name, PyObject *co, const char *pathname, const char *cpathname)
|
||||
|
||||
Like :c:func:`PyImport_ExecCodeModuleObject`, but *name*, *pathname* and
|
||||
*cpathname* are UTF-8 encoded strings. Attempts are also made to figure out
|
||||
what the value for *pathname* should be from *cpathname* if the former is
|
||||
set to ``NULL``.
|
||||
|
||||
.. versionadded:: 3.2
|
||||
.. versionchanged:: 3.3
|
||||
Uses :func:`imp.source_from_cache()` in calculating the source path if
|
||||
only the bytecode path is provided.
|
||||
|
||||
|
||||
.. c:function:: long PyImport_GetMagicNumber()
|
||||
|
||||
Return the magic number for Python bytecode files (a.k.a. :file:`.pyc` file).
|
||||
The magic number should be present in the first four bytes of the bytecode
|
||||
file, in little-endian byte order. Returns ``-1`` on error.
|
||||
|
||||
.. versionchanged:: 3.3
|
||||
Return value of ``-1`` upon failure.
|
||||
|
||||
|
||||
.. c:function:: const char * PyImport_GetMagicTag()
|
||||
|
||||
Return the magic tag string for :pep:`3147` format Python bytecode file
|
||||
names. Keep in mind that the value at ``sys.implementation.cache_tag`` is
|
||||
authoritative and should be used instead of this function.
|
||||
|
||||
.. versionadded:: 3.2
|
||||
|
||||
.. 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_GetModule(PyObject *name)
|
||||
|
||||
Return the already imported module with the given name. If the
|
||||
module has not been imported yet then returns NULL but does not set
|
||||
an error. Returns NULL and sets an error if the lookup failed.
|
||||
|
||||
.. versionadded:: 3.7
|
||||
|
||||
.. c:function:: PyObject* PyImport_GetImporter(PyObject *path)
|
||||
|
||||
Return a finder 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 that the :term:`path based finder` could not find a
|
||||
finder for this path item. Cache the result in :data:`sys.path_importer_cache`.
|
||||
Return a new reference to the finder object.
|
||||
|
||||
|
||||
.. 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:: int PyImport_ImportFrozenModuleObject(PyObject *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.)
|
||||
|
||||
.. versionadded:: 3.3
|
||||
|
||||
.. versionchanged:: 3.4
|
||||
The ``__file__`` attribute is no longer set on the module.
|
||||
|
||||
|
||||
.. c:function:: int PyImport_ImportFrozenModule(const char *name)
|
||||
|
||||
Similar to :c:func:`PyImport_ImportFrozenModuleObject`, but the name is a
|
||||
UTF-8 encoded string instead of a Unicode object.
|
||||
|
||||
|
||||
.. 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 {
|
||||
const char *name;
|
||||
const unsigned char *code;
|
||||
int size;
|
||||
};
|
||||
|
||||
|
||||
.. c:var:: const 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, PyObject* (*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. The name is an ASCII encoded string. 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 {
|
||||
const char *name; /* ASCII encoded string */
|
||||
PyObject* (*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`.
|
||||
@ -0,0 +1,26 @@
|
||||
.. _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
|
||||
stable.rst
|
||||
veryhigh.rst
|
||||
refcounting.rst
|
||||
exceptions.rst
|
||||
utilities.rst
|
||||
abstract.rst
|
||||
concrete.rst
|
||||
init.rst
|
||||
memory.rst
|
||||
objimpl.rst
|
||||
apiabiversion.rst
|
||||
File diff suppressed because it is too large
Load Diff
@ -0,0 +1,725 @@
|
||||
.. 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.
|
||||
|
||||
|
||||
Coding standards
|
||||
================
|
||||
|
||||
If you're writing C code for inclusion in CPython, you **must** follow the
|
||||
guidelines and standards defined in :PEP:`7`. These guidelines apply
|
||||
regardless of the version of Python you are contributing to. Following these
|
||||
conventions is not necessary for your own third party extension modules,
|
||||
unless you eventually expect to contribute them to Python.
|
||||
|
||||
|
||||
.. _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::
|
||||
|
||||
#define PY_SSIZE_T_CLEAN
|
||||
#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.
|
||||
|
||||
It is recommended to always define ``PY_SSIZE_T_CLEAN`` before including
|
||||
``Python.h``. See :ref:`arg-parsing` for a description of this macro.
|
||||
|
||||
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
|
||||
``'%d.%d' % sys.version_info[:2]``. 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++.
|
||||
|
||||
|
||||
Useful macros
|
||||
=============
|
||||
|
||||
Several useful macros are defined in the Python header files. Many are
|
||||
defined closer to where they are useful (e.g. :c:macro:`Py_RETURN_NONE`).
|
||||
Others of a more general utility are defined here. This is not necessarily a
|
||||
complete listing.
|
||||
|
||||
.. c:macro:: Py_UNREACHABLE()
|
||||
|
||||
Use this when you have a code path that you do not expect to be reached.
|
||||
For example, in the ``default:`` clause in a ``switch`` statement for which
|
||||
all possible values are covered in ``case`` statements. Use this in places
|
||||
where you might be tempted to put an ``assert(0)`` or ``abort()`` call.
|
||||
|
||||
.. versionadded:: 3.7
|
||||
|
||||
.. c:macro:: Py_ABS(x)
|
||||
|
||||
Return the absolute value of ``x``.
|
||||
|
||||
.. versionadded:: 3.3
|
||||
|
||||
.. c:macro:: Py_MIN(x, y)
|
||||
|
||||
Return the minimum value between ``x`` and ``y``.
|
||||
|
||||
.. versionadded:: 3.3
|
||||
|
||||
.. c:macro:: Py_MAX(x, y)
|
||||
|
||||
Return the maximum value between ``x`` and ``y``.
|
||||
|
||||
.. versionadded:: 3.3
|
||||
|
||||
.. c:macro:: Py_STRINGIFY(x)
|
||||
|
||||
Convert ``x`` to a C string. E.g. ``Py_STRINGIFY(123)`` returns
|
||||
``"123"``.
|
||||
|
||||
.. versionadded:: 3.4
|
||||
|
||||
.. c:macro:: Py_MEMBER_SIZE(type, member)
|
||||
|
||||
Return the size of a structure (``type``) ``member`` in bytes.
|
||||
|
||||
.. versionadded:: 3.6
|
||||
|
||||
.. c:macro:: Py_CHARMASK(c)
|
||||
|
||||
Argument must be a character or an integer in the range [-128, 127] or [0,
|
||||
255]. This macro returns ``c`` cast to an ``unsigned char``.
|
||||
|
||||
.. c:macro:: Py_GETENV(s)
|
||||
|
||||
Like ``getenv(s)``, but returns *NULL* if :option:`-E` was passed on the
|
||||
command line (i.e. if ``Py_IgnoreEnvironmentFlag`` is set).
|
||||
|
||||
.. c:macro:: Py_UNUSED(arg)
|
||||
|
||||
Use this for unused arguments in a function definition to silence compiler
|
||||
warnings, e.g. ``PyObject* func(PyObject *Py_UNUSED(ignored))``.
|
||||
|
||||
.. versionadded:: 3.4
|
||||
|
||||
|
||||
.. _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, PyLong_FromLong(1L));
|
||||
PyTuple_SetItem(t, 1, PyLong_FromLong(2L));
|
||||
PyTuple_SetItem(t, 2, PyUnicode_FromString("three"));
|
||||
|
||||
Here, :c:func:`PyLong_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)
|
||||
{
|
||||
Py_ssize_t i, n;
|
||||
|
||||
n = PyObject_Length(target);
|
||||
if (n < 0)
|
||||
return -1;
|
||||
for (i = 0; i < n; i++) {
|
||||
PyObject *index = PyLong_FromSsize_t(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)
|
||||
{
|
||||
Py_ssize_t i, n;
|
||||
long total = 0, value;
|
||||
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 (!PyLong_Check(item)) continue; /* Skip non-integers */
|
||||
value = PyLong_AsLong(item);
|
||||
if (value == -1 && PyErr_Occurred())
|
||||
/* Integer too big to fit in a C long, bail out */
|
||||
return -1;
|
||||
total += value;
|
||||
}
|
||||
return total;
|
||||
}
|
||||
|
||||
.. index:: single: sum_list()
|
||||
|
||||
::
|
||||
|
||||
long
|
||||
sum_sequence(PyObject *sequence)
|
||||
{
|
||||
Py_ssize_t i, n;
|
||||
long total = 0, value;
|
||||
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 (PyLong_Check(item)) {
|
||||
value = PyLong_AsLong(item);
|
||||
Py_DECREF(item);
|
||||
if (value == -1 && PyErr_Occurred())
|
||||
/* Integer too big to fit in a C long, bail out */
|
||||
return -1;
|
||||
total += value;
|
||||
}
|
||||
else {
|
||||
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.
|
||||
|
||||
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 result of
|
||||
``sys.exc_info()``; 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_info()`` 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 = PyLong_FromLong(0L);
|
||||
if (item == NULL)
|
||||
goto error;
|
||||
}
|
||||
const_one = PyLong_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: builtins
|
||||
module: __main__
|
||||
module: sys
|
||||
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:`builtins`, :mod:`__main__`, and :mod:`sys`. 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_FinalizeEx`. 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_FinalizeEx`
|
||||
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 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.
|
||||
|
||||
@ -0,0 +1,46 @@
|
||||
.. highlightlang:: c
|
||||
|
||||
.. _iterator:
|
||||
|
||||
Iterator Protocol
|
||||
=================
|
||||
|
||||
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.
|
||||
|
||||
|
||||
.. 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 */
|
||||
}
|
||||
@ -0,0 +1,50 @@
|
||||
.. 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.
|
||||
|
||||
|
||||
.. c:function:: int PySeqIter_Check(op)
|
||||
|
||||
Return true if the type of *op* is :c:data:`PySeqIter_Type`.
|
||||
|
||||
|
||||
.. 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.
|
||||
|
||||
|
||||
.. 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.
|
||||
|
||||
|
||||
.. c:function:: int PyCallIter_Check(op)
|
||||
|
||||
Return true if the type of *op* is :c:data:`PyCallIter_Type`.
|
||||
|
||||
|
||||
.. 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.
|
||||
@ -0,0 +1,151 @@
|
||||
.. 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 :class:`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.
|
||||
|
||||
|
||||
.. 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.
|
||||
|
||||
|
||||
.. 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`.
|
||||
|
||||
|
||||
.. 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.
|
||||
|
||||
|
||||
.. c:function:: Py_ssize_t PyList_GET_SIZE(PyObject *list)
|
||||
|
||||
Macro form of :c:func:`PyList_Size` without error checking.
|
||||
|
||||
|
||||
.. 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 non-negative; indexing from the end of the list is not
|
||||
supported. If *index* is out of bounds (<0 or >=len(list)),
|
||||
return *NULL* and set an :exc:`IndexError` exception.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyList_GET_ITEM(PyObject *list, Py_ssize_t i)
|
||||
|
||||
Macro form of :c:func:`PyList_GetItem` without error checking.
|
||||
|
||||
|
||||
.. 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.
|
||||
|
||||
|
||||
.. 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
|
||||
is being replaced; any reference in *list* at position *i* will be
|
||||
leaked.
|
||||
|
||||
|
||||
.. 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)``.
|
||||
|
||||
|
||||
.. 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.
|
||||
|
||||
|
||||
.. 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.
|
||||
|
||||
|
||||
.. 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)``.
|
||||
|
||||
|
||||
.. c:function:: int PyList_ClearFreeList()
|
||||
|
||||
Clear the free list. Return the total number of freed items.
|
||||
|
||||
.. versionadded:: 3.3
|
||||
@ -0,0 +1,297 @@
|
||||
.. highlightlang:: c
|
||||
|
||||
.. _longobjects:
|
||||
|
||||
Integer Objects
|
||||
---------------
|
||||
|
||||
.. index:: object: long integer
|
||||
object: integer
|
||||
|
||||
All integers are implemented as "long" integer objects of arbitrary size.
|
||||
|
||||
On error, most ``PyLong_As*`` APIs return ``(return type)-1`` which cannot be
|
||||
distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
|
||||
|
||||
.. c:type:: PyLongObject
|
||||
|
||||
This subtype of :c:type:`PyObject` represents a Python integer object.
|
||||
|
||||
|
||||
.. c:var:: PyTypeObject PyLong_Type
|
||||
|
||||
This instance of :c:type:`PyTypeObject` represents the Python integer type.
|
||||
This is the same object as :class:`int` in the Python layer.
|
||||
|
||||
|
||||
.. c:function:: int PyLong_Check(PyObject *p)
|
||||
|
||||
Return true if its argument is a :c:type:`PyLongObject` or a subtype of
|
||||
:c:type:`PyLongObject`.
|
||||
|
||||
|
||||
.. 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`.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyLong_FromLong(long v)
|
||||
|
||||
Return a new :c:type:`PyLongObject` object from *v*, or *NULL* on failure.
|
||||
|
||||
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* 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.
|
||||
|
||||
|
||||
.. 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.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyLong_FromLongLong(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 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(const 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``, *str* is interpreted using
|
||||
the :ref:`integers` definition; in this case, leading zeros in a
|
||||
non-zero decimal number raises a :exc:`ValueError`. If *base* is not ``0``,
|
||||
it must be between ``2`` and ``36``, inclusive. Leading spaces and single
|
||||
underscores after a base specifier and between digits 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 integer value. The Unicode
|
||||
string is first encoded to a byte string using :c:func:`PyUnicode_EncodeDecimal`
|
||||
and then converted using :c:func:`PyLong_FromString`.
|
||||
|
||||
.. deprecated-removed:: 3.3 4.0
|
||||
Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using
|
||||
:c:func:`PyLong_FromUnicodeObject`.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyLong_FromUnicodeObject(PyObject *u, int base)
|
||||
|
||||
Convert a sequence of Unicode digits in the string *u* to a Python integer
|
||||
value. The Unicode string is first encoded to a byte string using
|
||||
:c:func:`PyUnicode_EncodeDecimal` and then converted using
|
||||
:c:func:`PyLong_FromString`.
|
||||
|
||||
.. versionadded:: 3.3
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyLong_FromVoidPtr(void *p)
|
||||
|
||||
Create a Python integer from the pointer *p*. The pointer value can be
|
||||
retrieved from the resulting value using :c:func:`PyLong_AsVoidPtr`.
|
||||
|
||||
|
||||
.. XXX alias PyLong_AS_LONG (for now)
|
||||
.. c:function:: long PyLong_AsLong(PyObject *obj)
|
||||
|
||||
.. index::
|
||||
single: LONG_MAX
|
||||
single: OverflowError (built-in exception)
|
||||
|
||||
Return a C :c:type:`long` representation of *obj*. If *obj* is not an
|
||||
instance of :c:type:`PyLongObject`, first call its :meth:`__int__` method
|
||||
(if present) to convert it to a :c:type:`PyLongObject`.
|
||||
|
||||
Raise :exc:`OverflowError` if the value of *obj* is out of range for a
|
||||
:c:type:`long`.
|
||||
|
||||
Returns ``-1`` on error. Use :c:func:`PyErr_Occurred` to disambiguate.
|
||||
|
||||
|
||||
.. c:function:: long PyLong_AsLongAndOverflow(PyObject *obj, int *overflow)
|
||||
|
||||
Return a C :c:type:`long` representation of *obj*. If *obj* is not an
|
||||
instance of :c:type:`PyLongObject`, first call its :meth:`__int__` method
|
||||
(if present) to convert it to a :c:type:`PyLongObject`.
|
||||
|
||||
If the value of *obj* 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 set *\*overflow* to ``0`` and return ``-1`` as usual.
|
||||
|
||||
Returns ``-1`` on error. Use :c:func:`PyErr_Occurred` to disambiguate.
|
||||
|
||||
|
||||
.. c:function:: long long PyLong_AsLongLong(PyObject *obj)
|
||||
|
||||
.. index::
|
||||
single: OverflowError (built-in exception)
|
||||
|
||||
Return a C :c:type:`long long` representation of *obj*. If *obj* is not an
|
||||
instance of :c:type:`PyLongObject`, first call its :meth:`__int__` method
|
||||
(if present) to convert it to a :c:type:`PyLongObject`.
|
||||
|
||||
Raise :exc:`OverflowError` if the value of *obj* is out of range for a
|
||||
:c:type:`long`.
|
||||
|
||||
Returns ``-1`` on error. Use :c:func:`PyErr_Occurred` to disambiguate.
|
||||
|
||||
|
||||
.. c:function:: long long PyLong_AsLongLongAndOverflow(PyObject *obj, int *overflow)
|
||||
|
||||
Return a C :c:type:`long long` representation of *obj*. If *obj* is not an
|
||||
instance of :c:type:`PyLongObject`, first call its :meth:`__int__` method
|
||||
(if present) to convert it to a :c:type:`PyLongObject`.
|
||||
|
||||
If the value of *obj* 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 set *\*overflow* to ``0`` and return ``-1`` as usual.
|
||||
|
||||
Returns ``-1`` on error. Use :c:func:`PyErr_Occurred` to disambiguate.
|
||||
|
||||
.. versionadded:: 3.2
|
||||
|
||||
|
||||
.. 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 *pylong*. *pylong* must
|
||||
be an instance of :c:type:`PyLongObject`.
|
||||
|
||||
Raise :exc:`OverflowError` if the value of *pylong* is out of range for a
|
||||
:c:type:`Py_ssize_t`.
|
||||
|
||||
Returns ``-1`` on error. Use :c:func:`PyErr_Occurred` to disambiguate.
|
||||
|
||||
|
||||
.. 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 *pylong*. *pylong*
|
||||
must be an instance of :c:type:`PyLongObject`.
|
||||
|
||||
Raise :exc:`OverflowError` if the value of *pylong* is out of range for a
|
||||
:c:type:`unsigned long`.
|
||||
|
||||
Returns ``(unsigned long)-1`` on error.
|
||||
Use :c:func:`PyErr_Occurred` to disambiguate.
|
||||
|
||||
|
||||
.. c:function:: size_t PyLong_AsSize_t(PyObject *pylong)
|
||||
|
||||
.. index::
|
||||
single: SIZE_MAX
|
||||
single: OverflowError (built-in exception)
|
||||
|
||||
Return a C :c:type:`size_t` representation of *pylong*. *pylong* must be
|
||||
an instance of :c:type:`PyLongObject`.
|
||||
|
||||
Raise :exc:`OverflowError` if the value of *pylong* is out of range for a
|
||||
:c:type:`size_t`.
|
||||
|
||||
Returns ``(size_t)-1`` on error.
|
||||
Use :c:func:`PyErr_Occurred` to disambiguate.
|
||||
|
||||
|
||||
.. c:function:: unsigned long long PyLong_AsUnsignedLongLong(PyObject *pylong)
|
||||
|
||||
.. index::
|
||||
single: OverflowError (built-in exception)
|
||||
|
||||
Return a C :c:type:`unsigned long long` representation of *pylong*. *pylong*
|
||||
must be an instance of :c:type:`PyLongObject`.
|
||||
|
||||
Raise :exc:`OverflowError` if the value of *pylong* is out of range for an
|
||||
:c:type:`unsigned long long`.
|
||||
|
||||
Returns ``(unsigned long long)-1`` on error.
|
||||
Use :c:func:`PyErr_Occurred` to disambiguate.
|
||||
|
||||
.. versionchanged:: 3.1
|
||||
A negative *pylong* now raises :exc:`OverflowError`, not :exc:`TypeError`.
|
||||
|
||||
|
||||
.. c:function:: unsigned long PyLong_AsUnsignedLongMask(PyObject *obj)
|
||||
|
||||
Return a C :c:type:`unsigned long` representation of *obj*. If *obj*
|
||||
is not an instance of :c:type:`PyLongObject`, first call its :meth:`__int__`
|
||||
method (if present) to convert it to a :c:type:`PyLongObject`.
|
||||
|
||||
If the value of *obj* is out of range for an :c:type:`unsigned long`,
|
||||
return the reduction of that value modulo ``ULONG_MAX + 1``.
|
||||
|
||||
Returns ``(unsigned long)-1`` on error. Use :c:func:`PyErr_Occurred` to
|
||||
disambiguate.
|
||||
|
||||
|
||||
.. c:function:: unsigned long long PyLong_AsUnsignedLongLongMask(PyObject *obj)
|
||||
|
||||
Return a C :c:type:`unsigned long long` representation of *obj*. If *obj*
|
||||
is not an instance of :c:type:`PyLongObject`, first call its :meth:`__int__`
|
||||
method (if present) to convert it to a :c:type:`PyLongObject`.
|
||||
|
||||
If the value of *obj* is out of range for an :c:type:`unsigned long long`,
|
||||
return the reduction of that value modulo ``PY_ULLONG_MAX + 1``.
|
||||
|
||||
Returns ``(unsigned long long)-1`` on error. Use :c:func:`PyErr_Occurred`
|
||||
to disambiguate.
|
||||
|
||||
|
||||
.. c:function:: double PyLong_AsDouble(PyObject *pylong)
|
||||
|
||||
Return a C :c:type:`double` representation of *pylong*. *pylong* must be
|
||||
an instance of :c:type:`PyLongObject`.
|
||||
|
||||
Raise :exc:`OverflowError` if the value of *pylong* is out of range for a
|
||||
:c:type:`double`.
|
||||
|
||||
Returns ``-1.0`` on error. Use :c:func:`PyErr_Occurred` to disambiguate.
|
||||
|
||||
|
||||
.. c:function:: void* PyLong_AsVoidPtr(PyObject *pylong)
|
||||
|
||||
Convert a Python 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`.
|
||||
|
||||
Returns *NULL* on error. Use :c:func:`PyErr_Occurred` to disambiguate.
|
||||
@ -0,0 +1,103 @@
|
||||
.. highlightlang:: c
|
||||
|
||||
.. _mapping:
|
||||
|
||||
Mapping Protocol
|
||||
================
|
||||
|
||||
See also :c:func:`PyObject_GetItem`, :c:func:`PyObject_SetItem` and
|
||||
:c:func:`PyObject_DelItem`.
|
||||
|
||||
|
||||
.. c:function:: int PyMapping_Check(PyObject *o)
|
||||
|
||||
Return ``1`` if the object provides mapping protocol or supports slicing,
|
||||
and ``0`` otherwise. Note that it returns ``1`` for Python classes with
|
||||
a :meth:`__getitem__` method since in general case it is impossible to
|
||||
determine what the type of keys it supports. 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.
|
||||
This is equivalent to the Python expression ``len(o)``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyMapping_GetItemString(PyObject *o, const char *key)
|
||||
|
||||
Return element of *o* corresponding to the string *key* or *NULL* on failure.
|
||||
This is the equivalent of the Python expression ``o[key]``.
|
||||
See also :c:func:`PyObject_GetItem`.
|
||||
|
||||
|
||||
.. c:function:: int PyMapping_SetItemString(PyObject *o, const char *key, PyObject *v)
|
||||
|
||||
Map the string *key* to the value *v* in object *o*. Returns ``-1`` on
|
||||
failure. This is the equivalent of the Python statement ``o[key] = v``.
|
||||
See also :c:func:`PyObject_SetItem`.
|
||||
|
||||
|
||||
.. c:function:: int PyMapping_DelItem(PyObject *o, PyObject *key)
|
||||
|
||||
Remove the mapping for the object *key* from the object *o*. Return ``-1``
|
||||
on failure. This is equivalent to the Python statement ``del o[key]``.
|
||||
This is an alias of :c:func:`PyObject_DelItem`.
|
||||
|
||||
|
||||
.. c:function:: int PyMapping_DelItemString(PyObject *o, const char *key)
|
||||
|
||||
Remove the mapping for the string *key* from the object *o*. Return ``-1``
|
||||
on failure. This is equivalent to the Python statement ``del o[key]``.
|
||||
|
||||
|
||||
.. 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 the Python expression ``key in o``.
|
||||
This function always succeeds.
|
||||
|
||||
Note that exceptions which occur while calling the :meth:`__getitem__`
|
||||
method will get suppressed.
|
||||
To get error reporting use :c:func:`PyObject_GetItem()` instead.
|
||||
|
||||
|
||||
.. c:function:: int PyMapping_HasKeyString(PyObject *o, const char *key)
|
||||
|
||||
Return ``1`` if the mapping object has the key *key* and ``0`` otherwise.
|
||||
This is equivalent to the Python expression ``key in o``.
|
||||
This function always succeeds.
|
||||
|
||||
Note that exceptions which occur while calling the :meth:`__getitem__`
|
||||
method and creating a temporary string object will get suppressed.
|
||||
To get error reporting use :c:func:`PyMapping_GetItemString()` instead.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyMapping_Keys(PyObject *o)
|
||||
|
||||
On success, return a list of the keys in object *o*. On failure, return
|
||||
*NULL*.
|
||||
|
||||
.. versionchanged:: 3.7
|
||||
Previously, the function returned a list or a tuple.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyMapping_Values(PyObject *o)
|
||||
|
||||
On success, return a list of the values in object *o*. On failure, return
|
||||
*NULL*.
|
||||
|
||||
.. versionchanged:: 3.7
|
||||
Previously, the function returned a list or a tuple.
|
||||
|
||||
|
||||
.. 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*.
|
||||
|
||||
.. versionchanged:: 3.7
|
||||
Previously, the function returned a list or a tuple.
|
||||
@ -0,0 +1,94 @@
|
||||
.. 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 shares interned strings in the file, and upon
|
||||
unmarshalling. Version 2 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. *version* indicates the file format.
|
||||
|
||||
|
||||
.. c:function:: void PyMarshal_WriteObjectToFile(PyObject *value, FILE *file, int version)
|
||||
|
||||
Marshal a Python object, *value*, to *file*.
|
||||
*version* indicates the file format.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyMarshal_WriteObjectToString(PyObject *value, int version)
|
||||
|
||||
Return a bytes object containing the marshalled representation of *value*.
|
||||
*version* indicates the file format.
|
||||
|
||||
|
||||
The following functions allow marshalled values to be read back in.
|
||||
|
||||
|
||||
.. 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`.
|
||||
|
||||
On error, sets the appropriate exception (:exc:`EOFError`) and returns
|
||||
``-1``.
|
||||
|
||||
|
||||
.. 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`.
|
||||
|
||||
On error, sets the appropriate exception (:exc:`EOFError`) and returns
|
||||
``-1``.
|
||||
|
||||
|
||||
.. 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`, :exc:`ValueError`
|
||||
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`, :exc:`ValueError`
|
||||
or :exc:`TypeError`) and returns *NULL*.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyMarshal_ReadObjectFromString(const char *data, Py_ssize_t len)
|
||||
|
||||
Return a Python object from the data stream in a byte buffer
|
||||
containing *len* bytes pointed to by *data*.
|
||||
|
||||
On error, sets the appropriate exception (:exc:`EOFError`, :exc:`ValueError`
|
||||
or :exc:`TypeError`) and returns *NULL*.
|
||||
|
||||
@ -0,0 +1,604 @@
|
||||
.. 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 = PyBytes_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 bytes 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.
|
||||
|
||||
.. seealso::
|
||||
|
||||
The :envvar:`PYTHONMALLOC` environment variable can be used to configure
|
||||
the memory allocators used by Python.
|
||||
|
||||
The :envvar:`PYTHONMALLOCSTATS` environment variable can be used to print
|
||||
statistics of the :ref:`pymalloc memory allocator <pymalloc>` every time a
|
||||
new pymalloc object arena is created, and on shutdown.
|
||||
|
||||
|
||||
Raw Memory Interface
|
||||
====================
|
||||
|
||||
The following function sets are wrappers to the system allocator. These
|
||||
functions are thread-safe, the :term:`GIL <global interpreter lock>` does not
|
||||
need to be held.
|
||||
|
||||
The :ref:`default raw memory allocator <default-memory-allocators>` uses
|
||||
the following functions: :c:func:`malloc`, :c:func:`calloc`, :c:func:`realloc`
|
||||
and :c:func:`free`; call ``malloc(1)`` (or ``calloc(1, 1)``) when requesting
|
||||
zero bytes.
|
||||
|
||||
.. versionadded:: 3.4
|
||||
|
||||
.. c:function:: void* PyMem_RawMalloc(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_RawMalloc(1)`` had been called instead. The memory will not have
|
||||
been initialized in any way.
|
||||
|
||||
|
||||
.. c:function:: void* PyMem_RawCalloc(size_t nelem, size_t elsize)
|
||||
|
||||
Allocates *nelem* elements each whose size in bytes is *elsize* and returns
|
||||
a pointer of type :c:type:`void\*` to the allocated memory, or *NULL* if the
|
||||
request fails. The memory is initialized to zeros.
|
||||
|
||||
Requesting zero elements or elements of size zero bytes returns a distinct
|
||||
non-*NULL* pointer if possible, as if ``PyMem_RawCalloc(1, 1)`` had been
|
||||
called instead.
|
||||
|
||||
.. versionadded:: 3.5
|
||||
|
||||
|
||||
.. c:function:: void* PyMem_RawRealloc(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_RawMalloc(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_RawMalloc`, :c:func:`PyMem_RawRealloc` or
|
||||
:c:func:`PyMem_RawCalloc`.
|
||||
|
||||
If the request fails, :c:func:`PyMem_RawRealloc` returns *NULL* and *p*
|
||||
remains a valid pointer to the previous memory area.
|
||||
|
||||
|
||||
.. c:function:: void PyMem_RawFree(void *p)
|
||||
|
||||
Frees the memory block pointed to by *p*, which must have been returned by a
|
||||
previous call to :c:func:`PyMem_RawMalloc`, :c:func:`PyMem_RawRealloc` or
|
||||
:c:func:`PyMem_RawCalloc`. Otherwise, or if ``PyMem_RawFree(p)`` has been
|
||||
called before, undefined behavior occurs.
|
||||
|
||||
If *p* is *NULL*, no operation is performed.
|
||||
|
||||
|
||||
.. _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.
|
||||
|
||||
The :ref:`default memory allocator <default-memory-allocators>` uses the
|
||||
:ref:`pymalloc memory allocator <pymalloc>`.
|
||||
|
||||
.. warning::
|
||||
|
||||
The :term:`GIL <global interpreter lock>` must be held when using these
|
||||
functions.
|
||||
|
||||
.. versionchanged:: 3.6
|
||||
|
||||
The default allocator is now pymalloc instead of system :c:func:`malloc`.
|
||||
|
||||
.. 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_Calloc(size_t nelem, size_t elsize)
|
||||
|
||||
Allocates *nelem* elements each whose size in bytes is *elsize* and returns
|
||||
a pointer of type :c:type:`void\*` to the allocated memory, or *NULL* if the
|
||||
request fails. The memory is initialized to zeros.
|
||||
|
||||
Requesting zero elements or elements of size zero bytes returns a distinct
|
||||
non-*NULL* pointer if possible, as if ``PyMem_Calloc(1, 1)`` had been called
|
||||
instead.
|
||||
|
||||
.. versionadded:: 3.5
|
||||
|
||||
|
||||
.. 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`, :c:func:`PyMem_Realloc` or :c:func:`PyMem_Calloc`.
|
||||
|
||||
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`, :c:func:`PyMem_Realloc` or
|
||||
:c:func:`PyMem_Calloc`. 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.
|
||||
|
||||
* ``PyMem_MALLOC(size)``
|
||||
* ``PyMem_NEW(type, size)``
|
||||
* ``PyMem_REALLOC(ptr, size)``
|
||||
* ``PyMem_RESIZE(ptr, type, size)``
|
||||
* ``PyMem_FREE(ptr)``
|
||||
* ``PyMem_DEL(ptr)``
|
||||
|
||||
|
||||
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.
|
||||
|
||||
The :ref:`default object allocator <default-memory-allocators>` uses the
|
||||
: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_Calloc(size_t nelem, size_t elsize)
|
||||
|
||||
Allocates *nelem* elements each whose size in bytes is *elsize* and returns
|
||||
a pointer of type :c:type:`void\*` to the allocated memory, or *NULL* if the
|
||||
request fails. The memory is initialized to zeros.
|
||||
|
||||
Requesting zero elements or elements of size zero bytes returns a distinct
|
||||
non-*NULL* pointer if possible, as if ``PyObject_Calloc(1, 1)`` had been called
|
||||
instead.
|
||||
|
||||
.. versionadded:: 3.5
|
||||
|
||||
|
||||
.. 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.
|
||||
|
||||
|
||||
.. _default-memory-allocators:
|
||||
|
||||
Default Memory Allocators
|
||||
=========================
|
||||
|
||||
Default memory allocators:
|
||||
|
||||
=============================== ==================== ================== ===================== ====================
|
||||
Configuration Name PyMem_RawMalloc PyMem_Malloc PyObject_Malloc
|
||||
=============================== ==================== ================== ===================== ====================
|
||||
Release build ``"pymalloc"`` ``malloc`` ``pymalloc`` ``pymalloc``
|
||||
Debug build ``"pymalloc_debug"`` ``malloc`` + debug ``pymalloc`` + debug ``pymalloc`` + debug
|
||||
Release build, without pymalloc ``"malloc"`` ``malloc`` ``malloc`` ``malloc``
|
||||
Debug build, without pymalloc ``"malloc_debug"`` ``malloc`` + debug ``malloc`` + debug ``malloc`` + debug
|
||||
=============================== ==================== ================== ===================== ====================
|
||||
|
||||
Legend:
|
||||
|
||||
* Name: value for :envvar:`PYTHONMALLOC` environment variable
|
||||
* ``malloc``: system allocators from the standard C library, C functions:
|
||||
:c:func:`malloc`, :c:func:`calloc`, :c:func:`realloc` and :c:func:`free`
|
||||
* ``pymalloc``: :ref:`pymalloc memory allocator <pymalloc>`
|
||||
* "+ debug": with debug hooks installed by :c:func:`PyMem_SetupDebugHooks`
|
||||
|
||||
|
||||
Customize Memory Allocators
|
||||
===========================
|
||||
|
||||
.. versionadded:: 3.4
|
||||
|
||||
.. c:type:: PyMemAllocatorEx
|
||||
|
||||
Structure used to describe a memory block allocator. The structure has
|
||||
four fields:
|
||||
|
||||
+----------------------------------------------------------+---------------------------------------+
|
||||
| Field | Meaning |
|
||||
+==========================================================+=======================================+
|
||||
| ``void *ctx`` | user context passed as first argument |
|
||||
+----------------------------------------------------------+---------------------------------------+
|
||||
| ``void* malloc(void *ctx, size_t size)`` | allocate a memory block |
|
||||
+----------------------------------------------------------+---------------------------------------+
|
||||
| ``void* calloc(void *ctx, size_t nelem, size_t elsize)`` | allocate a memory block initialized |
|
||||
| | with zeros |
|
||||
+----------------------------------------------------------+---------------------------------------+
|
||||
| ``void* realloc(void *ctx, void *ptr, size_t new_size)`` | allocate or resize a memory block |
|
||||
+----------------------------------------------------------+---------------------------------------+
|
||||
| ``void free(void *ctx, void *ptr)`` | free a memory block |
|
||||
+----------------------------------------------------------+---------------------------------------+
|
||||
|
||||
.. versionchanged:: 3.5
|
||||
The :c:type:`PyMemAllocator` structure was renamed to
|
||||
:c:type:`PyMemAllocatorEx` and a new ``calloc`` field was added.
|
||||
|
||||
|
||||
.. c:type:: PyMemAllocatorDomain
|
||||
|
||||
Enum used to identify an allocator domain. Domains:
|
||||
|
||||
.. c:var:: PYMEM_DOMAIN_RAW
|
||||
|
||||
Functions:
|
||||
|
||||
* :c:func:`PyMem_RawMalloc`
|
||||
* :c:func:`PyMem_RawRealloc`
|
||||
* :c:func:`PyMem_RawCalloc`
|
||||
* :c:func:`PyMem_RawFree`
|
||||
|
||||
.. c:var:: PYMEM_DOMAIN_MEM
|
||||
|
||||
Functions:
|
||||
|
||||
* :c:func:`PyMem_Malloc`,
|
||||
* :c:func:`PyMem_Realloc`
|
||||
* :c:func:`PyMem_Calloc`
|
||||
* :c:func:`PyMem_Free`
|
||||
|
||||
.. c:var:: PYMEM_DOMAIN_OBJ
|
||||
|
||||
Functions:
|
||||
|
||||
* :c:func:`PyObject_Malloc`
|
||||
* :c:func:`PyObject_Realloc`
|
||||
* :c:func:`PyObject_Calloc`
|
||||
* :c:func:`PyObject_Free`
|
||||
|
||||
.. c:function:: void PyMem_GetAllocator(PyMemAllocatorDomain domain, PyMemAllocatorEx *allocator)
|
||||
|
||||
Get the memory block allocator of the specified domain.
|
||||
|
||||
|
||||
.. c:function:: void PyMem_SetAllocator(PyMemAllocatorDomain domain, PyMemAllocatorEx *allocator)
|
||||
|
||||
Set the memory block allocator of the specified domain.
|
||||
|
||||
The new allocator must return a distinct non-NULL pointer when requesting
|
||||
zero bytes.
|
||||
|
||||
For the :c:data:`PYMEM_DOMAIN_RAW` domain, the allocator must be
|
||||
thread-safe: the :term:`GIL <global interpreter lock>` is not held when the
|
||||
allocator is called.
|
||||
|
||||
If the new allocator is not a hook (does not call the previous allocator),
|
||||
the :c:func:`PyMem_SetupDebugHooks` function must be called to reinstall the
|
||||
debug hooks on top on the new allocator.
|
||||
|
||||
|
||||
.. c:function:: void PyMem_SetupDebugHooks(void)
|
||||
|
||||
Setup hooks to detect bugs in the Python memory allocator functions.
|
||||
|
||||
Newly allocated memory is filled with the byte ``0xCD`` (``CLEANBYTE``),
|
||||
freed memory is filled with the byte ``0xDD`` (``DEADBYTE``). Memory blocks
|
||||
are surrounded by "forbidden bytes" (``FORBIDDENBYTE``: byte ``0xFD``).
|
||||
|
||||
Runtime checks:
|
||||
|
||||
- Detect API violations, ex: :c:func:`PyObject_Free` called on a buffer
|
||||
allocated by :c:func:`PyMem_Malloc`
|
||||
- Detect write before the start of the buffer (buffer underflow)
|
||||
- Detect write after the end of the buffer (buffer overflow)
|
||||
- Check that the :term:`GIL <global interpreter lock>` is held when
|
||||
allocator functions of :c:data:`PYMEM_DOMAIN_OBJ` (ex:
|
||||
:c:func:`PyObject_Malloc`) and :c:data:`PYMEM_DOMAIN_MEM` (ex:
|
||||
:c:func:`PyMem_Malloc`) domains are called
|
||||
|
||||
On error, the debug hooks use the :mod:`tracemalloc` module to get the
|
||||
traceback where a memory block was allocated. The traceback is only
|
||||
displayed if :mod:`tracemalloc` is tracing Python memory allocations and the
|
||||
memory block was traced.
|
||||
|
||||
These hooks are :ref:`installed by default <default-memory-allocators>` if
|
||||
Python is compiled in debug
|
||||
mode. The :envvar:`PYTHONMALLOC` environment variable can be used to install
|
||||
debug hooks on a Python compiled in release mode.
|
||||
|
||||
.. versionchanged:: 3.6
|
||||
This function now also works on Python compiled in release mode.
|
||||
On error, the debug hooks now use :mod:`tracemalloc` to get the traceback
|
||||
where a memory block was allocated. The debug hooks now also check
|
||||
if the GIL is held when functions of :c:data:`PYMEM_DOMAIN_OBJ` and
|
||||
:c:data:`PYMEM_DOMAIN_MEM` domains are called.
|
||||
|
||||
.. versionchanged:: 3.7.3
|
||||
Byte patterns ``0xCB`` (``CLEANBYTE``), ``0xDB`` (``DEADBYTE``) and
|
||||
``0xFB`` (``FORBIDDENBYTE``) have been replaced with ``0xCD``, ``0xDD``
|
||||
and ``0xFD`` to use the same values than Windows CRT debug ``malloc()``
|
||||
and ``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:`PyMem_RawMalloc` and
|
||||
:c:func:`PyMem_RawRealloc` for allocations larger than 512 bytes.
|
||||
|
||||
*pymalloc* is the :ref:`default allocator <default-memory-allocators>` of the
|
||||
:c:data:`PYMEM_DOMAIN_MEM` (ex: :c:func:`PyMem_Malloc`) and
|
||||
:c:data:`PYMEM_DOMAIN_OBJ` (ex: :c:func:`PyObject_Malloc`) domains.
|
||||
|
||||
The arena allocator uses the following functions:
|
||||
|
||||
* :c:func:`VirtualAlloc` and :c:func:`VirtualFree` on Windows,
|
||||
* :c:func:`mmap` and :c:func:`munmap` if available,
|
||||
* :c:func:`malloc` and :c:func:`free` otherwise.
|
||||
|
||||
Customize pymalloc Arena Allocator
|
||||
----------------------------------
|
||||
|
||||
.. versionadded:: 3.4
|
||||
|
||||
.. c:type:: PyObjectArenaAllocator
|
||||
|
||||
Structure used to describe an arena allocator. The structure has
|
||||
three fields:
|
||||
|
||||
+--------------------------------------------------+---------------------------------------+
|
||||
| Field | Meaning |
|
||||
+==================================================+=======================================+
|
||||
| ``void *ctx`` | user context passed as first argument |
|
||||
+--------------------------------------------------+---------------------------------------+
|
||||
| ``void* alloc(void *ctx, size_t size)`` | allocate an arena of size bytes |
|
||||
+--------------------------------------------------+---------------------------------------+
|
||||
| ``void free(void *ctx, size_t size, void *ptr)`` | free an arena |
|
||||
+--------------------------------------------------+---------------------------------------+
|
||||
|
||||
.. c:function:: PyObject_GetArenaAllocator(PyObjectArenaAllocator *allocator)
|
||||
|
||||
Get the arena allocator.
|
||||
|
||||
.. c:function:: PyObject_SetArenaAllocator(PyObjectArenaAllocator *allocator)
|
||||
|
||||
Set the arena allocator.
|
||||
|
||||
|
||||
tracemalloc C API
|
||||
=================
|
||||
|
||||
.. versionadded:: 3.7
|
||||
|
||||
.. c:function: int PyTraceMalloc_Track(unsigned int domain, uintptr_t ptr, size_t size)
|
||||
|
||||
Track an allocated memory block in the :mod:`tracemalloc` module.
|
||||
|
||||
Return ``0`` on success, return ``-1`` on error (failed to allocate memory to
|
||||
store the trace). Return ``-2`` if tracemalloc is disabled.
|
||||
|
||||
If memory block is already tracked, update the existing trace.
|
||||
|
||||
.. c:function: int PyTraceMalloc_Untrack(unsigned int domain, uintptr_t ptr)
|
||||
|
||||
Untrack an allocated memory block in the :mod:`tracemalloc` module.
|
||||
Do nothing if the block was not tracked.
|
||||
|
||||
Return ``-2`` if tracemalloc is disabled, otherwise return ``0``.
|
||||
|
||||
|
||||
.. _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 = PyBytes_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 = PyBytes_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.
|
||||
|
||||
@ -0,0 +1,63 @@
|
||||
.. highlightlang:: c
|
||||
|
||||
.. _memoryview-objects:
|
||||
|
||||
.. index::
|
||||
object: memoryview
|
||||
|
||||
MemoryView objects
|
||||
------------------
|
||||
|
||||
A :class:`memoryview` object exposes the C level :ref:`buffer interface
|
||||
<bufferobjects>` 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 provides the buffer interface.
|
||||
If *obj* supports writable buffer exports, the memoryview object will be
|
||||
read/write, otherwise it may be either read-only or read/write at the
|
||||
discretion of the exporter.
|
||||
|
||||
.. c:function:: PyObject *PyMemoryView_FromMemory(char *mem, Py_ssize_t size, int flags)
|
||||
|
||||
Create a memoryview object using *mem* as the underlying buffer.
|
||||
*flags* can be one of :c:macro:`PyBUF_READ` or :c:macro:`PyBUF_WRITE`.
|
||||
|
||||
.. versionadded:: 3.3
|
||||
|
||||
.. c:function:: PyObject *PyMemoryView_FromBuffer(Py_buffer *view)
|
||||
|
||||
Create a memoryview object wrapping the given buffer structure *view*.
|
||||
For simple byte buffers, :c:func:`PyMemoryView_FromMemory` is the preferred
|
||||
function.
|
||||
|
||||
.. c:function:: PyObject *PyMemoryView_GetContiguous(PyObject *obj, int buffertype, char order)
|
||||
|
||||
Create a memoryview object to a :term:`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, a 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 *mview)
|
||||
|
||||
Return a pointer to the memoryview's private copy of the exporter's buffer.
|
||||
*mview* **must** be a memoryview instance; this macro doesn't check its type,
|
||||
you must do it yourself or you will risk crashes.
|
||||
|
||||
.. c:function:: Py_buffer *PyMemoryView_GET_BASE(PyObject *mview)
|
||||
|
||||
Return either a pointer to the exporting object that the memoryview is based
|
||||
on or *NULL* if the memoryview has been created by one of the functions
|
||||
:c:func:`PyMemoryView_FromMemory` or :c:func:`PyMemoryView_FromBuffer`.
|
||||
*mview* **must** be a memoryview instance.
|
||||
|
||||
@ -0,0 +1,100 @@
|
||||
.. highlightlang:: c
|
||||
|
||||
.. _instancemethod-objects:
|
||||
|
||||
Instance Method Objects
|
||||
-----------------------
|
||||
|
||||
.. index:: object: instancemethod
|
||||
|
||||
An instance method is a wrapper for a :c:data:`PyCFunction` and the new way
|
||||
to bind a :c:data:`PyCFunction` to a class object. It replaces the former call
|
||||
``PyMethod_New(func, NULL, class)``.
|
||||
|
||||
|
||||
.. c:var:: PyTypeObject PyInstanceMethod_Type
|
||||
|
||||
This instance of :c:type:`PyTypeObject` represents the Python instance
|
||||
method type. It is not exposed to Python programs.
|
||||
|
||||
|
||||
.. c:function:: int PyInstanceMethod_Check(PyObject *o)
|
||||
|
||||
Return true if *o* is an instance method object (has type
|
||||
:c:data:`PyInstanceMethod_Type`). The parameter must not be *NULL*.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyInstanceMethod_New(PyObject *func)
|
||||
|
||||
Return a new instance method object, with *func* being any callable object
|
||||
*func* is the function that will be called when the instance method is
|
||||
called.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyInstanceMethod_Function(PyObject *im)
|
||||
|
||||
Return the function object associated with the instance method *im*.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyInstanceMethod_GET_FUNCTION(PyObject *im)
|
||||
|
||||
Macro version of :c:func:`PyInstanceMethod_Function` which avoids error checking.
|
||||
|
||||
|
||||
.. _method-objects:
|
||||
|
||||
Method Objects
|
||||
--------------
|
||||
|
||||
.. index:: object: method
|
||||
|
||||
Methods are bound function objects. Methods are always bound to an instance of
|
||||
a user-defined class. Unbound methods (methods bound to a class object) are
|
||||
no longer available.
|
||||
|
||||
|
||||
.. 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)
|
||||
|
||||
Return a new method object, with *func* being any callable object and *self*
|
||||
the instance the method should be bound. *func* is the function that will
|
||||
be called when the method is called. *self* must not be *NULL*.
|
||||
|
||||
|
||||
.. 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*.
|
||||
|
||||
|
||||
.. 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.
|
||||
|
||||
@ -0,0 +1,479 @@
|
||||
.. highlightlang:: c
|
||||
|
||||
.. _moduleobjects:
|
||||
|
||||
Module Objects
|
||||
--------------
|
||||
|
||||
.. index:: object: module
|
||||
|
||||
|
||||
.. 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.
|
||||
|
||||
|
||||
.. c:function:: int PyModule_CheckExact(PyObject *p)
|
||||
|
||||
Return true if *p* is a module object, but not a subtype of
|
||||
:c:data:`PyModule_Type`.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyModule_NewObject(PyObject *name)
|
||||
|
||||
.. index::
|
||||
single: __name__ (module attribute)
|
||||
single: __doc__ (module attribute)
|
||||
single: __file__ (module attribute)
|
||||
single: __package__ (module attribute)
|
||||
single: __loader__ (module attribute)
|
||||
|
||||
Return a new module object with the :attr:`__name__` attribute set to *name*.
|
||||
The module's :attr:`__name__`, :attr:`__doc__`, :attr:`__package__`, and
|
||||
:attr:`__loader__` attributes are filled in (all but :attr:`__name__` are set
|
||||
to ``None``); the caller is responsible for providing a :attr:`__file__`
|
||||
attribute.
|
||||
|
||||
.. versionadded:: 3.3
|
||||
|
||||
.. versionchanged:: 3.4
|
||||
:attr:`__package__` and :attr:`__loader__` are set to ``None``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyModule_New(const char *name)
|
||||
|
||||
Similar to :c:func:`PyModule_NewObject`, but the name is a UTF-8 encoded
|
||||
string instead of a Unicode object.
|
||||
|
||||
|
||||
.. 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.
|
||||
If *module* is not a module object (or a subtype of a module object),
|
||||
:exc:`SystemError` is raised and *NULL* is returned.
|
||||
|
||||
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:: PyObject* PyModule_GetNameObject(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.
|
||||
|
||||
.. versionadded:: 3.3
|
||||
|
||||
|
||||
.. c:function:: const char* PyModule_GetName(PyObject *module)
|
||||
|
||||
Similar to :c:func:`PyModule_GetNameObject` but return the name encoded to
|
||||
``'utf-8'``.
|
||||
|
||||
.. c:function:: void* PyModule_GetState(PyObject *module)
|
||||
|
||||
Return the "state" of the module, that is, a pointer to the block of memory
|
||||
allocated at module creation time, or *NULL*. See
|
||||
:c:member:`PyModuleDef.m_size`.
|
||||
|
||||
|
||||
.. c:function:: PyModuleDef* PyModule_GetDef(PyObject *module)
|
||||
|
||||
Return a pointer to the :c:type:`PyModuleDef` struct from which the module was
|
||||
created, or *NULL* if the module wasn't created from a definition.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyModule_GetFilenameObject(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
|
||||
unicode string, raise :exc:`SystemError` and return *NULL*; otherwise return
|
||||
a reference to a Unicode object.
|
||||
|
||||
.. versionadded:: 3.2
|
||||
|
||||
|
||||
.. c:function:: const char* PyModule_GetFilename(PyObject *module)
|
||||
|
||||
Similar to :c:func:`PyModule_GetFilenameObject` but return the filename
|
||||
encoded to 'utf-8'.
|
||||
|
||||
.. deprecated:: 3.2
|
||||
:c:func:`PyModule_GetFilename` raises :c:type:`UnicodeEncodeError` on
|
||||
unencodable filenames, use :c:func:`PyModule_GetFilenameObject` instead.
|
||||
|
||||
|
||||
.. _initializing-modules:
|
||||
|
||||
Initializing C modules
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Modules objects are usually created from extension modules (shared libraries
|
||||
which export an initialization function), or compiled-in modules
|
||||
(where the initialization function is added using :c:func:`PyImport_AppendInittab`).
|
||||
See :ref:`building` or :ref:`extending-with-embedding` for details.
|
||||
|
||||
The initialization function can either pass a module definition instance
|
||||
to :c:func:`PyModule_Create`, and return the resulting module object,
|
||||
or request "multi-phase initialization" by returning the definition struct itself.
|
||||
|
||||
.. c:type:: PyModuleDef
|
||||
|
||||
The module definition struct, which holds all information needed to create
|
||||
a module object. There is usually only one statically initialized variable
|
||||
of this type for each module.
|
||||
|
||||
.. c:member:: PyModuleDef_Base m_base
|
||||
|
||||
Always initialize this member to :const:`PyModuleDef_HEAD_INIT`.
|
||||
|
||||
.. c:member:: const char *m_name
|
||||
|
||||
Name for the new module.
|
||||
|
||||
.. c:member:: const char *m_doc
|
||||
|
||||
Docstring for the module; usually a docstring variable created with
|
||||
:c:func:`PyDoc_STRVAR` is used.
|
||||
|
||||
.. c:member:: Py_ssize_t m_size
|
||||
|
||||
Module state may be kept in a per-module memory area that can be
|
||||
retrieved with :c:func:`PyModule_GetState`, rather than in static globals.
|
||||
This makes modules safe for use in multiple sub-interpreters.
|
||||
|
||||
This memory area is allocated based on *m_size* on module creation,
|
||||
and freed when the module object is deallocated, after the
|
||||
:c:member:`m_free` function has been called, if present.
|
||||
|
||||
Setting ``m_size`` to ``-1`` means that the module does not support
|
||||
sub-interpreters, because it has global state.
|
||||
|
||||
Setting it to a non-negative value means that the module can be
|
||||
re-initialized and specifies the additional amount of memory it requires
|
||||
for its state. Non-negative ``m_size`` is required for multi-phase
|
||||
initialization.
|
||||
|
||||
See :PEP:`3121` for more details.
|
||||
|
||||
.. c:member:: PyMethodDef* m_methods
|
||||
|
||||
A pointer to a table of module-level functions, described by
|
||||
:c:type:`PyMethodDef` values. Can be *NULL* if no functions are present.
|
||||
|
||||
.. c:member:: PyModuleDef_Slot* m_slots
|
||||
|
||||
An array of slot definitions for multi-phase initialization, terminated by
|
||||
a ``{0, NULL}`` entry.
|
||||
When using single-phase initialization, *m_slots* must be *NULL*.
|
||||
|
||||
.. versionchanged:: 3.5
|
||||
|
||||
Prior to version 3.5, this member was always set to *NULL*,
|
||||
and was defined as:
|
||||
|
||||
.. c:member:: inquiry m_reload
|
||||
|
||||
.. c:member:: traverseproc m_traverse
|
||||
|
||||
A traversal function to call during GC traversal of the module object, or
|
||||
*NULL* if not needed. This function may be called before module state
|
||||
is allocated (:c:func:`PyModule_GetState()` may return `NULL`),
|
||||
and before the :c:member:`Py_mod_exec` function is executed.
|
||||
|
||||
.. c:member:: inquiry m_clear
|
||||
|
||||
A clear function to call during GC clearing of the module object, or
|
||||
*NULL* if not needed. This function may be called before module state
|
||||
is allocated (:c:func:`PyModule_GetState()` may return `NULL`),
|
||||
and before the :c:member:`Py_mod_exec` function is executed.
|
||||
|
||||
.. c:member:: freefunc m_free
|
||||
|
||||
A function to call during deallocation of the module object, or *NULL* if
|
||||
not needed. This function may be called before module state
|
||||
is allocated (:c:func:`PyModule_GetState()` may return `NULL`),
|
||||
and before the :c:member:`Py_mod_exec` function is executed.
|
||||
|
||||
Single-phase initialization
|
||||
...........................
|
||||
|
||||
The module initialization function may create and return the module object
|
||||
directly. This is referred to as "single-phase initialization", and uses one
|
||||
of the following two module creation functions:
|
||||
|
||||
.. c:function:: PyObject* PyModule_Create(PyModuleDef *def)
|
||||
|
||||
Create a new module object, given the definition in *def*. This behaves
|
||||
like :c:func:`PyModule_Create2` with *module_api_version* set to
|
||||
:const:`PYTHON_API_VERSION`.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyModule_Create2(PyModuleDef *def, int module_api_version)
|
||||
|
||||
Create a new module object, given the definition in *def*, assuming the
|
||||
API version *module_api_version*. If that version does not match the version
|
||||
of the running interpreter, a :exc:`RuntimeWarning` is emitted.
|
||||
|
||||
.. note::
|
||||
|
||||
Most uses of this function should be using :c:func:`PyModule_Create`
|
||||
instead; only use this if you are sure you need it.
|
||||
|
||||
Before it is returned from in the initialization function, the resulting module
|
||||
object is typically populated using functions like :c:func:`PyModule_AddObject`.
|
||||
|
||||
.. _multi-phase-initialization:
|
||||
|
||||
Multi-phase initialization
|
||||
..........................
|
||||
|
||||
An alternate way to specify extensions is to request "multi-phase initialization".
|
||||
Extension modules created this way behave more like Python modules: the
|
||||
initialization is split between the *creation phase*, when the module object
|
||||
is created, and the *execution phase*, when it is populated.
|
||||
The distinction is similar to the :py:meth:`__new__` and :py:meth:`__init__` methods
|
||||
of classes.
|
||||
|
||||
Unlike modules created using single-phase initialization, these modules are not
|
||||
singletons: if the *sys.modules* entry is removed and the module is re-imported,
|
||||
a new module object is created, and the old module is subject to normal garbage
|
||||
collection -- as with Python modules.
|
||||
By default, multiple modules created from the same definition should be
|
||||
independent: changes to one should not affect the others.
|
||||
This means that all state should be specific to the module object (using e.g.
|
||||
using :c:func:`PyModule_GetState`), or its contents (such as the module's
|
||||
:attr:`__dict__` or individual classes created with :c:func:`PyType_FromSpec`).
|
||||
|
||||
All modules created using multi-phase initialization are expected to support
|
||||
:ref:`sub-interpreters <sub-interpreter-support>`. Making sure multiple modules
|
||||
are independent is typically enough to achieve this.
|
||||
|
||||
To request multi-phase initialization, the initialization function
|
||||
(PyInit_modulename) returns a :c:type:`PyModuleDef` instance with non-empty
|
||||
:c:member:`~PyModuleDef.m_slots`. Before it is returned, the ``PyModuleDef``
|
||||
instance must be initialized with the following function:
|
||||
|
||||
.. c:function:: PyObject* PyModuleDef_Init(PyModuleDef *def)
|
||||
|
||||
Ensures a module definition is a properly initialized Python object that
|
||||
correctly reports its type and reference count.
|
||||
|
||||
Returns *def* cast to ``PyObject*``, or *NULL* if an error occurred.
|
||||
|
||||
.. versionadded:: 3.5
|
||||
|
||||
The *m_slots* member of the module definition must point to an array of
|
||||
``PyModuleDef_Slot`` structures:
|
||||
|
||||
.. c:type:: PyModuleDef_Slot
|
||||
|
||||
.. c:member:: int slot
|
||||
|
||||
A slot ID, chosen from the available values explained below.
|
||||
|
||||
.. c:member:: void* value
|
||||
|
||||
Value of the slot, whose meaning depends on the slot ID.
|
||||
|
||||
.. versionadded:: 3.5
|
||||
|
||||
The *m_slots* array must be terminated by a slot with id 0.
|
||||
|
||||
The available slot types are:
|
||||
|
||||
.. c:var:: Py_mod_create
|
||||
|
||||
Specifies a function that is called to create the module object itself.
|
||||
The *value* pointer of this slot must point to a function of the signature:
|
||||
|
||||
.. c:function:: PyObject* create_module(PyObject *spec, PyModuleDef *def)
|
||||
|
||||
The function receives a :py:class:`~importlib.machinery.ModuleSpec`
|
||||
instance, as defined in :PEP:`451`, and the module definition.
|
||||
It should return a new module object, or set an error
|
||||
and return *NULL*.
|
||||
|
||||
This function should be kept minimal. In particular, it should not
|
||||
call arbitrary Python code, as trying to import the same module again may
|
||||
result in an infinite loop.
|
||||
|
||||
Multiple ``Py_mod_create`` slots may not be specified in one module
|
||||
definition.
|
||||
|
||||
If ``Py_mod_create`` is not specified, the import machinery will create
|
||||
a normal module object using :c:func:`PyModule_New`. The name is taken from
|
||||
*spec*, not the definition, to allow extension modules to dynamically adjust
|
||||
to their place in the module hierarchy and be imported under different
|
||||
names through symlinks, all while sharing a single module definition.
|
||||
|
||||
There is no requirement for the returned object to be an instance of
|
||||
:c:type:`PyModule_Type`. Any type can be used, as long as it supports
|
||||
setting and getting import-related attributes.
|
||||
However, only ``PyModule_Type`` instances may be returned if the
|
||||
``PyModuleDef`` has non-*NULL* ``m_traverse``, ``m_clear``,
|
||||
``m_free``; non-zero ``m_size``; or slots other than ``Py_mod_create``.
|
||||
|
||||
.. c:var:: Py_mod_exec
|
||||
|
||||
Specifies a function that is called to *execute* the module.
|
||||
This is equivalent to executing the code of a Python module: typically,
|
||||
this function adds classes and constants to the module.
|
||||
The signature of the function is:
|
||||
|
||||
.. c:function:: int exec_module(PyObject* module)
|
||||
|
||||
If multiple ``Py_mod_exec`` slots are specified, they are processed in the
|
||||
order they appear in the *m_slots* array.
|
||||
|
||||
See :PEP:`489` for more details on multi-phase initialization.
|
||||
|
||||
Low-level module creation functions
|
||||
...................................
|
||||
|
||||
The following functions are called under the hood when using multi-phase
|
||||
initialization. They can be used directly, for example when creating module
|
||||
objects dynamically. Note that both ``PyModule_FromDefAndSpec`` and
|
||||
``PyModule_ExecDef`` must be called to fully initialize a module.
|
||||
|
||||
.. c:function:: PyObject * PyModule_FromDefAndSpec(PyModuleDef *def, PyObject *spec)
|
||||
|
||||
Create a new module object, given the definition in *module* and the
|
||||
ModuleSpec *spec*. This behaves like :c:func:`PyModule_FromDefAndSpec2`
|
||||
with *module_api_version* set to :const:`PYTHON_API_VERSION`.
|
||||
|
||||
.. versionadded:: 3.5
|
||||
|
||||
.. c:function:: PyObject * PyModule_FromDefAndSpec2(PyModuleDef *def, PyObject *spec, int module_api_version)
|
||||
|
||||
Create a new module object, given the definition in *module* and the
|
||||
ModuleSpec *spec*, assuming the API version *module_api_version*.
|
||||
If that version does not match the version of the running interpreter,
|
||||
a :exc:`RuntimeWarning` is emitted.
|
||||
|
||||
.. note::
|
||||
|
||||
Most uses of this function should be using :c:func:`PyModule_FromDefAndSpec`
|
||||
instead; only use this if you are sure you need it.
|
||||
|
||||
.. versionadded:: 3.5
|
||||
|
||||
.. c:function:: int PyModule_ExecDef(PyObject *module, PyModuleDef *def)
|
||||
|
||||
Process any execution slots (:c:data:`Py_mod_exec`) given in *def*.
|
||||
|
||||
.. versionadded:: 3.5
|
||||
|
||||
.. c:function:: int PyModule_SetDocString(PyObject *module, const char *docstring)
|
||||
|
||||
Set the docstring for *module* to *docstring*.
|
||||
This function is called automatically when creating a module from
|
||||
``PyModuleDef``, using either ``PyModule_Create`` or
|
||||
``PyModule_FromDefAndSpec``.
|
||||
|
||||
.. versionadded:: 3.5
|
||||
|
||||
.. c:function:: int PyModule_AddFunctions(PyObject *module, PyMethodDef *functions)
|
||||
|
||||
Add the functions from the *NULL* terminated *functions* array to *module*.
|
||||
Refer to the :c:type:`PyMethodDef` documentation for details on individual
|
||||
entries (due to the lack of a shared module namespace, module level
|
||||
"functions" implemented in C typically receive the module as their first
|
||||
parameter, making them similar to instance methods on Python classes).
|
||||
This function is called automatically when creating a module from
|
||||
``PyModuleDef``, using either ``PyModule_Create`` or
|
||||
``PyModule_FromDefAndSpec``.
|
||||
|
||||
.. versionadded:: 3.5
|
||||
|
||||
Support functions
|
||||
.................
|
||||
|
||||
The module initialization function (if using single phase initialization) or
|
||||
a function called from a module execution slot (if using multi-phase
|
||||
initialization), can use the following functions to help initialize the module
|
||||
state:
|
||||
|
||||
.. 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.
|
||||
|
||||
.. 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.
|
||||
|
||||
|
||||
.. 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.
|
||||
|
||||
|
||||
.. 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.
|
||||
|
||||
|
||||
.. c:function:: int PyModule_AddStringMacro(PyObject *module, macro)
|
||||
|
||||
Add a string constant to *module*.
|
||||
|
||||
|
||||
Module lookup
|
||||
^^^^^^^^^^^^^
|
||||
|
||||
Single-phase initialization creates singleton modules that can be looked up
|
||||
in the context of the current interpreter. This allows the module object to be
|
||||
retrieved later with only a reference to the module definition.
|
||||
|
||||
These functions will not work on modules created using multi-phase initialization,
|
||||
since multiple such modules can be created from a single definition.
|
||||
|
||||
.. c:function:: PyObject* PyState_FindModule(PyModuleDef *def)
|
||||
|
||||
Returns the module object that was created from *def* for the current interpreter.
|
||||
This method requires that the module object has been attached to the interpreter state with
|
||||
:c:func:`PyState_AddModule` beforehand. In case the corresponding module object is not
|
||||
found or has not been attached to the interpreter state yet, it returns *NULL*.
|
||||
|
||||
.. c:function:: int PyState_AddModule(PyObject *module, PyModuleDef *def)
|
||||
|
||||
Attaches the module object passed to the function to the interpreter state. This allows
|
||||
the module object to be accessible via :c:func:`PyState_FindModule`.
|
||||
|
||||
Only effective on modules created using single-phase initialization.
|
||||
|
||||
.. versionadded:: 3.3
|
||||
|
||||
.. c:function:: int PyState_RemoveModule(PyModuleDef *def)
|
||||
|
||||
Removes the module object created from *def* from the interpreter state.
|
||||
|
||||
.. versionadded:: 3.3
|
||||
@ -0,0 +1,26 @@
|
||||
.. 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 (that is,
|
||||
increment the reference count of ``None`` and return it.)
|
||||
@ -0,0 +1,283 @@
|
||||
.. 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_MatrixMultiply(PyObject *o1, PyObject *o2)
|
||||
|
||||
Returns the result of matrix multiplication on *o1* and *o2*, or *NULL* on
|
||||
failure. This is the equivalent of the Python expression ``o1 @ o2``.
|
||||
|
||||
.. versionadded:: 3.5
|
||||
|
||||
|
||||
.. 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.
|
||||
|
||||
|
||||
.. 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.
|
||||
|
||||
|
||||
.. 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_InPlaceMatrixMultiply(PyObject *o1, PyObject *o2)
|
||||
|
||||
Returns the result of matrix multiplication on *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``.
|
||||
|
||||
.. versionadded:: 3.5
|
||||
|
||||
|
||||
.. 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``.
|
||||
|
||||
|
||||
.. 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.
|
||||
|
||||
|
||||
.. 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:: PyObject* PyNumber_Long(PyObject *o)
|
||||
|
||||
.. index:: builtin: int
|
||||
|
||||
Returns the *o* converted to an integer object on success, or *NULL* on
|
||||
failure. This is the equivalent of the Python expression ``int(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 on success or *NULL* with a
|
||||
:exc:`TypeError` exception raised on failure.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyNumber_ToBase(PyObject *n, int base)
|
||||
|
||||
Returns the integer *n* converted to base *base* as a string. The *base*
|
||||
argument must be one of 2, 8, 10, or 16. For base 2, 8, or 16, the
|
||||
returned string is prefixed with a base marker of ``'0b'``, ``'0o'``, or
|
||||
``'0x'``, respectively. If *n* is not a Python int, it is converted with
|
||||
:c:func:`PyNumber_Index` first.
|
||||
|
||||
|
||||
.. 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 the call fails, an exception is raised and ``-1`` is returned.
|
||||
|
||||
If *o* can be converted to a Python int 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.
|
||||
|
||||
|
||||
.. 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.
|
||||
This function always succeeds.
|
||||
@ -0,0 +1,55 @@
|
||||
.. highlightlang:: c
|
||||
|
||||
Old Buffer Protocol
|
||||
-------------------
|
||||
|
||||
.. deprecated:: 3.0
|
||||
|
||||
These functions were part of the "old buffer protocol" API in Python 2.
|
||||
In Python 3, this protocol doesn't exist anymore but the functions are still
|
||||
exposed to ease porting 2.x code. They act as a compatibility wrapper
|
||||
around the :ref:`new buffer protocol <bufferobjects>`, but they don't give
|
||||
you control over the lifetime of the resources acquired when a buffer is
|
||||
exported.
|
||||
|
||||
Therefore, it is recommended that you call :c:func:`PyObject_GetBuffer`
|
||||
(or the ``y*`` or ``w*`` :ref:`format codes <arg-parsing>` with the
|
||||
:c:func:`PyArg_ParseTuple` family of functions) to get a buffer view over
|
||||
an object, and :c:func:`PyBuffer_Release` when the buffer view can be released.
|
||||
|
||||
|
||||
.. 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.
|
||||
|
||||
|
||||
.. 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.
|
||||
|
||||
|
||||
.. c:function:: int PyObject_CheckReadBuffer(PyObject *o)
|
||||
|
||||
Returns ``1`` if *o* supports the single-segment readable buffer interface.
|
||||
Otherwise returns ``0``. This function always succeeds.
|
||||
|
||||
Note that this function tries to get and release a buffer, and exceptions
|
||||
which occur while calling corresponding functions will get suppressed.
|
||||
To get error reporting use :c:func:`PyObject_GetBuffer()` instead.
|
||||
|
||||
|
||||
.. c:function:: int PyObject_AsWriteBuffer(PyObject *obj, void **buffer, Py_ssize_t *buffer_len)
|
||||
|
||||
Returns a pointer to a writable 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.
|
||||
|
||||
@ -0,0 +1,451 @@
|
||||
.. highlightlang:: c
|
||||
|
||||
.. _object:
|
||||
|
||||
Object Protocol
|
||||
===============
|
||||
|
||||
|
||||
.. c:var:: PyObject* Py_NotImplemented
|
||||
|
||||
The ``NotImplemented`` singleton, used to signal that an operation is
|
||||
not implemented for the given type combination.
|
||||
|
||||
|
||||
.. c:macro:: Py_RETURN_NOTIMPLEMENTED
|
||||
|
||||
Properly handle returning :c:data:`Py_NotImplemented` from within a C
|
||||
function (that is, increment the reference count of NotImplemented and
|
||||
return it).
|
||||
|
||||
|
||||
.. 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.
|
||||
|
||||
Note that exceptions which occur while calling :meth:`__getattr__` and
|
||||
:meth:`__getattribute__` methods will get suppressed.
|
||||
To get error reporting use :c:func:`PyObject_GetAttr()` instead.
|
||||
|
||||
|
||||
.. 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.
|
||||
|
||||
Note that exceptions which occur while calling :meth:`__getattr__` and
|
||||
:meth:`__getattribute__` methods and creating a temporary string object
|
||||
will get suppressed.
|
||||
To get error reporting use :c:func:`PyObject_GetAttrString()` instead.
|
||||
|
||||
|
||||
.. 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_GenericGetDict(PyObject *o, void *context)
|
||||
|
||||
A generic implementation for the getter of a ``__dict__`` descriptor. It
|
||||
creates the dictionary if necessary.
|
||||
|
||||
.. versionadded:: 3.3
|
||||
|
||||
|
||||
.. c:function:: int PyObject_GenericSetDict(PyObject *o, void *context)
|
||||
|
||||
A generic implementation for the setter of a ``__dict__`` descriptor. This
|
||||
implementation does not allow the dictionary to be deleted.
|
||||
|
||||
.. versionadded:: 3.3
|
||||
|
||||
|
||||
.. 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:: 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.
|
||||
|
||||
.. versionchanged:: 3.4
|
||||
This function now includes a debug assertion to help ensure that it
|
||||
does not silently discard an active exception.
|
||||
|
||||
.. c:function:: PyObject* PyObject_ASCII(PyObject *o)
|
||||
|
||||
.. index:: builtin: ascii
|
||||
|
||||
As :c:func:`PyObject_Repr`, compute a string representation of object *o*, but
|
||||
escape the non-ASCII characters in the string returned by
|
||||
:c:func:`PyObject_Repr` with ``\x``, ``\u`` or ``\U`` escapes. This generates
|
||||
a string similar to that returned by :c:func:`PyObject_Repr` in Python 2.
|
||||
Called by the :func:`ascii` built-in function.
|
||||
|
||||
.. index:: string; PyObject_Str (C function)
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyObject_Str(PyObject *o)
|
||||
|
||||
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, therefore, by the :func:`print` function.
|
||||
|
||||
.. versionchanged:: 3.4
|
||||
This function now includes a debug assertion to help ensure that it
|
||||
does not silently discard an active exception.
|
||||
|
||||
.. c:function:: PyObject* PyObject_Bytes(PyObject *o)
|
||||
|
||||
.. index:: builtin: bytes
|
||||
|
||||
Compute a bytes representation of object *o*. *NULL* is returned on
|
||||
failure and a bytes object on success. This is equivalent to the Python
|
||||
expression ``bytes(o)``, when *o* is not an integer. Unlike ``bytes(o)``,
|
||||
a TypeError is raised when *o* is an integer instead of a zero-initialized
|
||||
bytes object.
|
||||
|
||||
|
||||
.. c:function:: int PyObject_IsSubclass(PyObject *derived, PyObject *cls)
|
||||
|
||||
Return ``1`` if the class *derived* is identical to or derived from the class
|
||||
*cls*, otherwise return ``0``. In case of an error, return ``-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 *cls* has a :meth:`~class.__subclasscheck__` method, it will be called to
|
||||
determine the subclass status as described in :pep:`3119`. Otherwise,
|
||||
*derived* is a subclass of *cls* if it is a direct or indirect subclass,
|
||||
i.e. contained in ``cls.__mro__``.
|
||||
|
||||
Normally only class objects, i.e. instances of :class:`type` or a derived
|
||||
class, are considered classes. However, objects can override this by having
|
||||
a :attr:`__bases__` attribute (which must be a tuple of base classes).
|
||||
|
||||
|
||||
.. c:function:: int PyObject_IsInstance(PyObject *inst, PyObject *cls)
|
||||
|
||||
Return ``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 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 *cls* has a :meth:`~class.__instancecheck__` method, it will be called to
|
||||
determine the subclass status as described in :pep:`3119`. Otherwise, *inst*
|
||||
is an instance of *cls* if its class is a subclass of *cls*.
|
||||
|
||||
An instance *inst* can override what is considered its class by having a
|
||||
:attr:`__class__` attribute.
|
||||
|
||||
An object *cls* can override if it is considered a class, and what its base
|
||||
classes are, by having a :attr:`__bases__` attribute (which must be a tuple
|
||||
of base classes).
|
||||
|
||||
|
||||
.. 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, PyObject *args, PyObject *kwargs)
|
||||
|
||||
Call a callable Python object *callable*, with arguments given by the
|
||||
tuple *args*, and named arguments given by the dictionary *kwargs*.
|
||||
|
||||
*args* must not be *NULL*, use an empty tuple if no arguments are needed.
|
||||
If no named arguments are needed, *kwargs* can be *NULL*.
|
||||
|
||||
Return the result of the call on success, or raise an exception and return
|
||||
*NULL* on failure.
|
||||
|
||||
This is the equivalent of the Python expression:
|
||||
``callable(*args, **kwargs)``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyObject_CallObject(PyObject *callable, PyObject *args)
|
||||
|
||||
Call a callable Python object *callable*, with arguments given by the
|
||||
tuple *args*. If no arguments are needed, then *args* can be *NULL*.
|
||||
|
||||
Return the result of the call on success, or raise an exception and return
|
||||
*NULL* on failure.
|
||||
|
||||
This is the equivalent of the Python expression: ``callable(*args)``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyObject_CallFunction(PyObject *callable, const char *format, ...)
|
||||
|
||||
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 can be *NULL*, indicating that no arguments are provided.
|
||||
|
||||
Return the result of the call on success, or raise an exception and return
|
||||
*NULL* on failure.
|
||||
|
||||
This is the equivalent of the Python expression: ``callable(*args)``.
|
||||
|
||||
Note that if you only pass :c:type:`PyObject \*` args,
|
||||
:c:func:`PyObject_CallFunctionObjArgs` is a faster alternative.
|
||||
|
||||
.. versionchanged:: 3.4
|
||||
The type of *format* was changed from ``char *``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyObject_CallMethod(PyObject *obj, const char *name, const char *format, ...)
|
||||
|
||||
Call the method named *name* of object *obj* 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 can be *NULL*, indicating that no arguments are provided.
|
||||
|
||||
Return the result of the call on success, or raise an exception and return
|
||||
*NULL* on failure.
|
||||
|
||||
This is the equivalent of the Python expression:
|
||||
``obj.name(arg1, arg2, ...)``.
|
||||
|
||||
Note that if you only pass :c:type:`PyObject \*` args,
|
||||
:c:func:`PyObject_CallMethodObjArgs` is a faster alternative.
|
||||
|
||||
.. versionchanged:: 3.4
|
||||
The types of *name* and *format* were changed from ``char *``.
|
||||
|
||||
|
||||
.. 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*.
|
||||
|
||||
Return the result of the call on success, or raise an exception and return
|
||||
*NULL* on failure.
|
||||
|
||||
This is the equivalent of the Python expression:
|
||||
``callable(arg1, arg2, ...)``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyObject_CallMethodObjArgs(PyObject *obj, PyObject *name, ..., NULL)
|
||||
|
||||
Calls a method of the Python object *obj*, 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*.
|
||||
|
||||
Return the result of the call on success, or raise an exception and return
|
||||
*NULL* on failure.
|
||||
|
||||
|
||||
.. c:function:: Py_hash_t 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)``.
|
||||
|
||||
.. versionchanged:: 3.2
|
||||
The return type is now Py_hash_t. This is a signed integer the same size
|
||||
as Py_ssize_t.
|
||||
|
||||
|
||||
.. c:function:: Py_hash_t 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.
|
||||
|
||||
|
||||
.. 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*.
|
||||
|
||||
|
||||
.. c:function:: Py_ssize_t PyObject_Size(PyObject *o)
|
||||
Py_ssize_t PyObject_Length(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)``.
|
||||
|
||||
|
||||
.. c:function:: Py_ssize_t PyObject_LengthHint(PyObject *o, Py_ssize_t default)
|
||||
|
||||
Return an estimated length for the object *o*. First try to return its
|
||||
actual length, then an estimate using :meth:`~object.__length_hint__`, and
|
||||
finally return the default value. On error return ``-1``. This is the
|
||||
equivalent to the Python expression ``operator.length_hint(o, default)``.
|
||||
|
||||
.. versionadded:: 3.4
|
||||
|
||||
|
||||
.. 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)
|
||||
|
||||
Remove the mapping for the object *key* from the object *o*. Return ``-1``
|
||||
on failure. This is equivalent to the Python statement ``del o[key]``.
|
||||
|
||||
|
||||
.. 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.
|
||||
@ -0,0 +1,17 @@
|
||||
.. 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
|
||||
@ -0,0 +1,73 @@
|
||||
.. 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.
|
||||
|
||||
|
||||
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`.
|
||||
|
||||
@ -0,0 +1,49 @@
|
||||
.. 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:: 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*.
|
||||
@ -0,0 +1,169 @@
|
||||
.. highlightlang:: c
|
||||
|
||||
.. _sequence:
|
||||
|
||||
Sequence Protocol
|
||||
=================
|
||||
|
||||
|
||||
.. c:function:: int PySequence_Check(PyObject *o)
|
||||
|
||||
Return ``1`` if the object provides sequence protocol, and ``0`` otherwise.
|
||||
Note that it returns ``1`` for Python classes with a :meth:`__getitem__`
|
||||
method unless they are :class:`dict` subclasses since in general case it
|
||||
is impossible to determine what the type of keys it supports. 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)``.
|
||||
|
||||
|
||||
.. 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``.
|
||||
|
||||
|
||||
.. 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``.
|
||||
|
||||
|
||||
.. 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]``.
|
||||
|
||||
|
||||
.. 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]``.
|
||||
|
||||
|
||||
.. 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`.
|
||||
|
||||
|
||||
.. 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]``.
|
||||
|
||||
|
||||
.. 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*. This is the equivalent of the Python statement ``o[i1:i2] = v``.
|
||||
|
||||
|
||||
.. 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]``.
|
||||
|
||||
|
||||
.. 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)``.
|
||||
|
||||
|
||||
.. 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)``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PySequence_List(PyObject *o)
|
||||
|
||||
Return a list object with the same contents as the sequence or iterable *o*,
|
||||
or *NULL* on failure. The returned list is guaranteed to be new. This is
|
||||
equivalent to the Python expression ``list(o)``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PySequence_Tuple(PyObject *o)
|
||||
|
||||
.. index:: builtin: tuple
|
||||
|
||||
Return a tuple object with the same contents as the sequence or iterable *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 or iterable *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 or iterable, raises :exc:`TypeError` with *m* as the message text.
|
||||
|
||||
|
||||
.. 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.
|
||||
|
||||
|
||||
.. 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.
|
||||
|
||||
|
||||
.. 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.
|
||||
|
||||
|
||||
.. 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.
|
||||
@ -0,0 +1,166 @@
|
||||
.. highlightlang:: c
|
||||
|
||||
.. _setobjects:
|
||||
|
||||
Set Objects
|
||||
-----------
|
||||
|
||||
.. sectionauthor:: Raymond D. Hettinger <python@rcn.com>
|
||||
|
||||
|
||||
.. index::
|
||||
object: set
|
||||
object: frozenset
|
||||
|
||||
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.
|
||||
|
||||
.. c:function:: int PyFrozenSet_Check(PyObject *p)
|
||||
|
||||
Return true if *p* is a :class:`frozenset` object or an instance of a
|
||||
subtype.
|
||||
|
||||
.. 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.
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
.. 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. Also works with :class:`frozenset`
|
||||
instances (like :c:func:`PyTuple_SetItem` it can be used to fill-in the values
|
||||
of brand new frozensets before they are exposed to other code). 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.
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
.. c:function:: int PySet_ClearFreeList()
|
||||
|
||||
Clear the free list. Return the total number of freed items.
|
||||
|
||||
.. versionadded:: 3.3
|
||||
@ -0,0 +1,122 @@
|
||||
.. highlightlang:: c
|
||||
|
||||
.. _slice-objects:
|
||||
|
||||
Slice Objects
|
||||
-------------
|
||||
|
||||
|
||||
.. c:var:: PyTypeObject PySlice_Type
|
||||
|
||||
The type object for slice objects. This is the same as :class:`slice` in the
|
||||
Python layer.
|
||||
|
||||
|
||||
.. 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(PyObject *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.
|
||||
|
||||
.. versionchanged:: 3.2
|
||||
The parameter type for the *slice* parameter was ``PySliceObject*``
|
||||
before.
|
||||
|
||||
|
||||
.. c:function:: int PySlice_GetIndicesEx(PyObject *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.
|
||||
|
||||
.. note::
|
||||
This function is considered not safe for resizable sequences.
|
||||
Its invocation should be replaced by a combination of
|
||||
:c:func:`PySlice_Unpack` and :c:func:`PySlice_AdjustIndices` where ::
|
||||
|
||||
if (PySlice_GetIndicesEx(slice, length, &start, &stop, &step, &slicelength) < 0) {
|
||||
// return error
|
||||
}
|
||||
|
||||
is replaced by ::
|
||||
|
||||
if (PySlice_Unpack(slice, &start, &stop, &step) < 0) {
|
||||
// return error
|
||||
}
|
||||
slicelength = PySlice_AdjustIndices(length, &start, &stop, step);
|
||||
|
||||
.. versionchanged:: 3.2
|
||||
The parameter type for the *slice* parameter was ``PySliceObject*``
|
||||
before.
|
||||
|
||||
.. versionchanged:: 3.6.1
|
||||
If ``Py_LIMITED_API`` is not set or set to the value between ``0x03050400``
|
||||
and ``0x03060000`` (not including) or ``0x03060100`` or higher
|
||||
:c:func:`!PySlice_GetIndicesEx` is implemented as a macro using
|
||||
:c:func:`!PySlice_Unpack` and :c:func:`!PySlice_AdjustIndices`.
|
||||
Arguments *start*, *stop* and *step* are evaluated more than once.
|
||||
|
||||
.. deprecated:: 3.6.1
|
||||
If ``Py_LIMITED_API`` is set to the value less than ``0x03050400`` or
|
||||
between ``0x03060000`` and ``0x03060100`` (not including)
|
||||
:c:func:`!PySlice_GetIndicesEx` is a deprecated function.
|
||||
|
||||
|
||||
.. c:function:: int PySlice_Unpack(PyObject *slice, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t *step)
|
||||
|
||||
Extract the start, stop and step data members from a slice object as
|
||||
C integers. Silently reduce values larger than ``PY_SSIZE_T_MAX`` to
|
||||
``PY_SSIZE_T_MAX``, silently boost the start and stop values less than
|
||||
``PY_SSIZE_T_MIN`` to ``PY_SSIZE_T_MIN``, and silently boost the step
|
||||
values less than ``-PY_SSIZE_T_MAX`` to ``-PY_SSIZE_T_MAX``.
|
||||
|
||||
Return ``-1`` on error, ``0`` on success.
|
||||
|
||||
.. versionadded:: 3.6.1
|
||||
|
||||
|
||||
.. c:function:: Py_ssize_t PySlice_AdjustIndices(Py_ssize_t length, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t step)
|
||||
|
||||
Adjust start/end slice indices assuming a sequence of the specified length.
|
||||
Out of bounds indices are clipped in a manner consistent with the handling
|
||||
of normal slices.
|
||||
|
||||
Return the length of the slice. Always successful. Doesn't call Python
|
||||
code.
|
||||
|
||||
.. versionadded:: 3.6.1
|
||||
|
||||
|
||||
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.
|
||||
@ -0,0 +1,38 @@
|
||||
.. highlightlang:: c
|
||||
|
||||
.. _stable:
|
||||
|
||||
***********************************
|
||||
Stable Application Binary Interface
|
||||
***********************************
|
||||
|
||||
Traditionally, the C API of Python will change with every release. Most changes
|
||||
will be source-compatible, typically by only adding API, rather than changing
|
||||
existing API or removing API (although some interfaces do get removed after
|
||||
being deprecated first).
|
||||
|
||||
Unfortunately, the API compatibility does not extend to binary compatibility
|
||||
(the ABI). The reason is primarily the evolution of struct definitions, where
|
||||
addition of a new field, or changing the type of a field, might not break the
|
||||
API, but can break the ABI. As a consequence, extension modules need to be
|
||||
recompiled for every Python release (although an exception is possible on Unix
|
||||
when none of the affected interfaces are used). In addition, on Windows,
|
||||
extension modules link with a specific pythonXY.dll and need to be recompiled to
|
||||
link with a newer one.
|
||||
|
||||
Since Python 3.2, a subset of the API has been declared to guarantee a stable
|
||||
ABI. Extension modules wishing to use this API (called "limited API") need to
|
||||
define ``Py_LIMITED_API``. A number of interpreter details then become hidden
|
||||
from the extension module; in return, a module is built that works on any 3.x
|
||||
version (x>=2) without recompilation.
|
||||
|
||||
In some cases, the stable ABI needs to be extended with new functions.
|
||||
Extension modules wishing to use these new APIs need to set ``Py_LIMITED_API``
|
||||
to the ``PY_VERSION_HEX`` value (see :ref:`apiabiversion`) of the minimum Python
|
||||
version they want to support (e.g. ``0x03030000`` for Python 3.3). Such modules
|
||||
will work on all subsequent Python releases, but fail to load (because of
|
||||
missing symbols) on the older releases.
|
||||
|
||||
As of Python 3.2, the set of functions available to the limited API is
|
||||
documented in :pep:`384`. In the C API documentation, API elements that are not
|
||||
part of the limited API are marked as "Not part of the limited API."
|
||||
@ -0,0 +1,376 @@
|
||||
.. 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.
|
||||
Nothing is actually declared to be a :c:type:`PyObject`, but every pointer
|
||||
to a Python object can be cast to a :c:type:`PyObject*`. Access to the
|
||||
members must be done by using the macros :c:macro:`Py_REFCNT` and
|
||||
:c:macro:`Py_TYPE`.
|
||||
|
||||
|
||||
.. 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.
|
||||
Access to the members must be done by using the macros
|
||||
:c:macro:`Py_REFCNT`, :c:macro:`Py_TYPE`, and :c:macro:`Py_SIZE`.
|
||||
|
||||
|
||||
.. c:macro:: PyObject_HEAD
|
||||
|
||||
This is a macro used when declaring new types which represent objects
|
||||
without a varying length. The PyObject_HEAD macro expands to::
|
||||
|
||||
PyObject ob_base;
|
||||
|
||||
See documentation of :c:type:`PyObject` above.
|
||||
|
||||
|
||||
.. c:macro:: PyObject_VAR_HEAD
|
||||
|
||||
This is a macro used when declaring new types which represent objects
|
||||
with a length that varies from instance to instance.
|
||||
The PyObject_VAR_HEAD macro expands to::
|
||||
|
||||
PyVarObject ob_base;
|
||||
|
||||
See documentation of :c:type:`PyVarObject` above.
|
||||
|
||||
|
||||
.. 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)
|
||||
|
||||
|
||||
.. 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)
|
||||
|
||||
|
||||
.. 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)
|
||||
|
||||
|
||||
.. 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:: PyCFunctionWithKeywords
|
||||
|
||||
Type of the functions used to implement Python callables in C
|
||||
with signature :const:`METH_VARARGS | METH_KEYWORDS`.
|
||||
|
||||
|
||||
.. c:type:: _PyCFunctionFast
|
||||
|
||||
Type of the functions used to implement Python callables in C
|
||||
with signature :const:`METH_FASTCALL`.
|
||||
|
||||
|
||||
.. c:type:: _PyCFunctionFastWithKeywords
|
||||
|
||||
Type of the functions used to implement Python callables in C
|
||||
with signature :const:`METH_FASTCALL | METH_KEYWORDS`.
|
||||
|
||||
|
||||
.. 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` | const 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` | const 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.
|
||||
|
||||
There are four basic calling conventions for positional arguments
|
||||
and two of them can be combined with :const:`METH_KEYWORDS` to support
|
||||
also keyword arguments. So there are a total of 6 calling conventions:
|
||||
|
||||
.. 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_VARARGS | METH_KEYWORDS
|
||||
|
||||
Methods with these flags must be of type :c:type:`PyCFunctionWithKeywords`.
|
||||
The function expects three parameters: *self*, *args*, *kwargs* where
|
||||
*kwargs* is a dictionary of all the keyword arguments or possibly *NULL*
|
||||
if there are no keyword arguments. The parameters are typically processed
|
||||
using :c:func:`PyArg_ParseTupleAndKeywords`.
|
||||
|
||||
|
||||
.. data:: METH_FASTCALL
|
||||
|
||||
Fast calling convention supporting only positional arguments.
|
||||
The methods have the type :c:type:`_PyCFunctionFast`.
|
||||
The first parameter is *self*, the second parameter is a C array
|
||||
of :c:type:`PyObject\*` values indicating the arguments and the third
|
||||
parameter is the number of arguments (the length of the array).
|
||||
|
||||
This is not part of the :ref:`limited API <stable>`.
|
||||
|
||||
.. versionadded:: 3.7
|
||||
|
||||
|
||||
.. data:: METH_FASTCALL | METH_KEYWORDS
|
||||
|
||||
Extension of :const:`METH_FASTCALL` supporting also keyword arguments,
|
||||
with methods of type :c:type:`_PyCFunctionFastWithKeywords`.
|
||||
Keyword arguments are passed the same way as in the vectorcall protocol:
|
||||
there is an additional fourth :c:type:`PyObject\*` parameter
|
||||
which is a tuple representing the names of the keyword arguments
|
||||
or possibly *NULL* if there are no keywords. The values of the keyword
|
||||
arguments are stored in the *args* array, after the positional arguments.
|
||||
|
||||
This is not part of the :ref:`limited API <stable>`.
|
||||
|
||||
.. versionadded:: 3.7
|
||||
|
||||
|
||||
.. 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.
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
.. 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.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
.. 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` | const 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` | const 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 const 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`. :c:macro:`T_STRING` data is interpreted as UTF-8.
|
||||
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 | const 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 | const 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.
|
||||
@ -0,0 +1,329 @@
|
||||
.. highlightlang:: c
|
||||
|
||||
.. _os:
|
||||
|
||||
Operating System Utilities
|
||||
==========================
|
||||
|
||||
.. c:function:: PyObject* PyOS_FSPath(PyObject *path)
|
||||
|
||||
Return the file system representation for *path*. If the object is a
|
||||
:class:`str` or :class:`bytes` object, then its reference count is
|
||||
incremented. If the object implements the :class:`os.PathLike` interface,
|
||||
then :meth:`~os.PathLike.__fspath__` is returned as long as it is a
|
||||
:class:`str` or :class:`bytes` object. Otherwise :exc:`TypeError` is raised
|
||||
and ``NULL`` is returned.
|
||||
|
||||
.. versionadded:: 3.6
|
||||
|
||||
|
||||
.. 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_BeforeFork()
|
||||
|
||||
Function to prepare some internal state before a process fork. This
|
||||
should be called before calling :c:func:`fork` or any similar function
|
||||
that clones the current process.
|
||||
Only available on systems where :c:func:`fork` is defined.
|
||||
|
||||
.. versionadded:: 3.7
|
||||
|
||||
|
||||
.. c:function:: void PyOS_AfterFork_Parent()
|
||||
|
||||
Function to update some internal state after a process fork. This
|
||||
should be called from the parent process after calling :c:func:`fork`
|
||||
or any similar function that clones the current process, regardless
|
||||
of whether process cloning was successful.
|
||||
Only available on systems where :c:func:`fork` is defined.
|
||||
|
||||
.. versionadded:: 3.7
|
||||
|
||||
|
||||
.. c:function:: void PyOS_AfterFork_Child()
|
||||
|
||||
Function to update internal interpreter state after a process fork.
|
||||
This must be called from the child process after calling :c:func:`fork`,
|
||||
or any similar function that clones the current process, if there is
|
||||
any chance the process will call back into the Python interpreter.
|
||||
Only available on systems where :c:func:`fork` is defined.
|
||||
|
||||
.. versionadded:: 3.7
|
||||
|
||||
.. seealso::
|
||||
:func:`os.register_at_fork` allows registering custom Python functions
|
||||
to be called by :c:func:`PyOS_BeforeFork()`,
|
||||
:c:func:`PyOS_AfterFork_Parent` and :c:func:`PyOS_AfterFork_Child`.
|
||||
|
||||
|
||||
.. 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.
|
||||
|
||||
.. deprecated:: 3.7
|
||||
This function is superseded by :c:func:`PyOS_AfterFork_Child()`.
|
||||
|
||||
|
||||
.. 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)`.
|
||||
|
||||
.. c:function:: wchar_t* Py_DecodeLocale(const char* arg, size_t *size)
|
||||
|
||||
Decode a byte string from the locale encoding with the :ref:`surrogateescape
|
||||
error handler <surrogateescape>`: undecodable bytes are decoded as
|
||||
characters in range U+DC80..U+DCFF. If a byte sequence can be decoded as a
|
||||
surrogate character, escape the bytes using the surrogateescape error
|
||||
handler instead of decoding them.
|
||||
|
||||
Encoding, highest priority to lowest priority:
|
||||
|
||||
* ``UTF-8`` on macOS and Android;
|
||||
* ``UTF-8`` if the Python UTF-8 mode is enabled;
|
||||
* ``ASCII`` if the ``LC_CTYPE`` locale is ``"C"``,
|
||||
``nl_langinfo(CODESET)`` returns the ``ASCII`` encoding (or an alias),
|
||||
and :c:func:`mbstowcs` and :c:func:`wcstombs` functions uses the
|
||||
``ISO-8859-1`` encoding.
|
||||
* the current locale encoding.
|
||||
|
||||
Return a pointer to a newly allocated wide character string, use
|
||||
:c:func:`PyMem_RawFree` to free the memory. If size is not ``NULL``, write
|
||||
the number of wide characters excluding the null character into ``*size``
|
||||
|
||||
Return ``NULL`` on decoding error or memory allocation error. If *size* is
|
||||
not ``NULL``, ``*size`` is set to ``(size_t)-1`` on memory error or set to
|
||||
``(size_t)-2`` on decoding error.
|
||||
|
||||
Decoding errors should never happen, unless there is a bug in the C
|
||||
library.
|
||||
|
||||
Use the :c:func:`Py_EncodeLocale` function to encode the character string
|
||||
back to a byte string.
|
||||
|
||||
.. seealso::
|
||||
|
||||
The :c:func:`PyUnicode_DecodeFSDefaultAndSize` and
|
||||
:c:func:`PyUnicode_DecodeLocaleAndSize` functions.
|
||||
|
||||
.. versionadded:: 3.5
|
||||
|
||||
.. versionchanged:: 3.7
|
||||
The function now uses the UTF-8 encoding in the UTF-8 mode.
|
||||
|
||||
|
||||
.. c:function:: char* Py_EncodeLocale(const wchar_t *text, size_t *error_pos)
|
||||
|
||||
Encode a wide character string to the locale encoding with the
|
||||
:ref:`surrogateescape error handler <surrogateescape>`: surrogate characters
|
||||
in the range U+DC80..U+DCFF are converted to bytes 0x80..0xFF.
|
||||
|
||||
Encoding, highest priority to lowest priority:
|
||||
|
||||
* ``UTF-8`` on macOS and Android;
|
||||
* ``UTF-8`` if the Python UTF-8 mode is enabled;
|
||||
* ``ASCII`` if the ``LC_CTYPE`` locale is ``"C"``,
|
||||
``nl_langinfo(CODESET)`` returns the ``ASCII`` encoding (or an alias),
|
||||
and :c:func:`mbstowcs` and :c:func:`wcstombs` functions uses the
|
||||
``ISO-8859-1`` encoding.
|
||||
* the current locale encoding.
|
||||
|
||||
The function uses the UTF-8 encoding in the Python UTF-8 mode.
|
||||
|
||||
Return a pointer to a newly allocated byte string, use :c:func:`PyMem_Free`
|
||||
to free the memory. Return ``NULL`` on encoding error or memory allocation
|
||||
error
|
||||
|
||||
If error_pos is not ``NULL``, ``*error_pos`` is set to ``(size_t)-1`` on
|
||||
success, or set to the index of the invalid character on encoding error.
|
||||
|
||||
Use the :c:func:`Py_DecodeLocale` function to decode the bytes string back
|
||||
to a wide character string.
|
||||
|
||||
.. versionchanged:: 3.7
|
||||
The function now uses the UTF-8 encoding in the UTF-8 mode.
|
||||
|
||||
.. seealso::
|
||||
|
||||
The :c:func:`PyUnicode_EncodeFSDefault` and
|
||||
:c:func:`PyUnicode_EncodeLocale` functions.
|
||||
|
||||
.. versionadded:: 3.5
|
||||
|
||||
.. versionchanged:: 3.7
|
||||
The function now supports the UTF-8 mode.
|
||||
|
||||
|
||||
.. _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(const char *name)
|
||||
|
||||
Return the object *name* from the :mod:`sys` module or *NULL* if it does
|
||||
not exist, without setting an exception.
|
||||
|
||||
.. c:function:: int PySys_SetObject(const 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. This function may be
|
||||
called prior to :c:func:`Py_Initialize`.
|
||||
|
||||
.. c:function:: void PySys_AddWarnOption(const wchar_t *s)
|
||||
|
||||
Append *s* to :data:`sys.warnoptions`. This function must be called prior
|
||||
to :c:func:`Py_Initialize` in order to affect the warnings filter list.
|
||||
|
||||
.. c:function:: void PySys_AddWarnOptionUnicode(PyObject *unicode)
|
||||
|
||||
Append *unicode* to :data:`sys.warnoptions`.
|
||||
|
||||
Note: this function is not currently usable from outside the CPython
|
||||
implementation, as it must be called prior to the implicit import of
|
||||
:mod:`warnings` in :c:func:`Py_Initialize` to be effective, but can't be
|
||||
called until enough of the runtime has been initialized to permit the
|
||||
creation of Unicode objects.
|
||||
|
||||
.. c:function:: void PySys_SetPath(const wchar_t *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 :c:func:`PySys_WriteStdout`, but write to :data:`sys.stderr` or *stderr*
|
||||
instead.
|
||||
|
||||
.. c:function:: void PySys_FormatStdout(const char *format, ...)
|
||||
|
||||
Function similar to PySys_WriteStdout() but format the message using
|
||||
:c:func:`PyUnicode_FromFormatV` and don't truncate the message to an
|
||||
arbitrary length.
|
||||
|
||||
.. versionadded:: 3.2
|
||||
|
||||
.. c:function:: void PySys_FormatStderr(const char *format, ...)
|
||||
|
||||
As :c:func:`PySys_FormatStdout`, but write to :data:`sys.stderr` or *stderr*
|
||||
instead.
|
||||
|
||||
.. versionadded:: 3.2
|
||||
|
||||
.. c:function:: void PySys_AddXOption(const wchar_t *s)
|
||||
|
||||
Parse *s* as a set of :option:`-X` options and add them to the current
|
||||
options mapping as returned by :c:func:`PySys_GetXOptions`. This function
|
||||
may be called prior to :c:func:`Py_Initialize`.
|
||||
|
||||
.. versionadded:: 3.2
|
||||
|
||||
.. c:function:: PyObject *PySys_GetXOptions()
|
||||
|
||||
Return the current dictionary of :option:`-X` options, similarly to
|
||||
:data:`sys._xoptions`. On error, *NULL* is returned and an exception is
|
||||
set.
|
||||
|
||||
.. versionadded:: 3.2
|
||||
|
||||
|
||||
.. _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_FinalizeEx()
|
||||
single: exit()
|
||||
|
||||
Exit the current process. This calls :c:func:`Py_FinalizeEx` and then calls the
|
||||
standard C library function ``exit(status)``. If :c:func:`Py_FinalizeEx`
|
||||
indicates an error, the exit status is set to 120.
|
||||
|
||||
.. versionchanged:: 3.6
|
||||
Errors from finalization no longer ignored.
|
||||
|
||||
|
||||
.. c:function:: int Py_AtExit(void (*func) ())
|
||||
|
||||
.. index::
|
||||
single: Py_FinalizeEx()
|
||||
single: cleanup functions
|
||||
|
||||
Register a cleanup function to be called by :c:func:`Py_FinalizeEx`. 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*.
|
||||
@ -0,0 +1,218 @@
|
||||
.. 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
|
||||
|
||||
This instance of :c:type:`PyTypeObject` represents the Python tuple type; it
|
||||
is the same object as :class:`tuple` 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.
|
||||
|
||||
|
||||
.. 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.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyTuple_New(Py_ssize_t len)
|
||||
|
||||
Return a new tuple object of size *len*, or *NULL* on failure.
|
||||
|
||||
|
||||
.. 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)``.
|
||||
|
||||
|
||||
.. c:function:: Py_ssize_t PyTuple_Size(PyObject *p)
|
||||
|
||||
Take a pointer to a tuple object, and return the size of that tuple.
|
||||
|
||||
|
||||
.. 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.
|
||||
|
||||
|
||||
.. 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.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyTuple_GET_ITEM(PyObject *p, Py_ssize_t pos)
|
||||
|
||||
Like :c:func:`PyTuple_GetItem`, but does no checking of its arguments.
|
||||
|
||||
|
||||
.. 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.
|
||||
|
||||
|
||||
.. 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*.
|
||||
|
||||
|
||||
.. 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*.
|
||||
|
||||
|
||||
.. 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`.
|
||||
|
||||
|
||||
.. c:function:: int PyTuple_ClearFreeList()
|
||||
|
||||
Clear the free list. Return the total number of freed items.
|
||||
|
||||
|
||||
Struct Sequence Objects
|
||||
-----------------------
|
||||
|
||||
Struct sequence objects are the C equivalent of :func:`~collections.namedtuple`
|
||||
objects, i.e. a sequence whose items can also be accessed through attributes.
|
||||
To create a struct sequence, you first have to create a specific struct sequence
|
||||
type.
|
||||
|
||||
.. c:function:: PyTypeObject* PyStructSequence_NewType(PyStructSequence_Desc *desc)
|
||||
|
||||
Create a new struct sequence type from the data in *desc*, described below. Instances
|
||||
of the resulting type can be created with :c:func:`PyStructSequence_New`.
|
||||
|
||||
|
||||
.. c:function:: void PyStructSequence_InitType(PyTypeObject *type, PyStructSequence_Desc *desc)
|
||||
|
||||
Initializes a struct sequence type *type* from *desc* in place.
|
||||
|
||||
|
||||
.. c:function:: int PyStructSequence_InitType2(PyTypeObject *type, PyStructSequence_Desc *desc)
|
||||
|
||||
The same as ``PyStructSequence_InitType``, but returns ``0`` on success and ``-1`` on
|
||||
failure.
|
||||
|
||||
.. versionadded:: 3.4
|
||||
|
||||
|
||||
.. c:type:: PyStructSequence_Desc
|
||||
|
||||
Contains the meta information of a struct sequence type to create.
|
||||
|
||||
+-------------------+------------------------------+------------------------------------+
|
||||
| Field | C Type | Meaning |
|
||||
+===================+==============================+====================================+
|
||||
| ``name`` | ``const char *`` | name of the struct sequence type |
|
||||
+-------------------+------------------------------+------------------------------------+
|
||||
| ``doc`` | ``const char *`` | pointer to docstring for the type |
|
||||
| | | or NULL to omit |
|
||||
+-------------------+------------------------------+------------------------------------+
|
||||
| ``fields`` | ``PyStructSequence_Field *`` | pointer to *NULL*-terminated array |
|
||||
| | | with field names of the new type |
|
||||
+-------------------+------------------------------+------------------------------------+
|
||||
| ``n_in_sequence`` | ``int`` | number of fields visible to the |
|
||||
| | | Python side (if used as tuple) |
|
||||
+-------------------+------------------------------+------------------------------------+
|
||||
|
||||
|
||||
.. c:type:: PyStructSequence_Field
|
||||
|
||||
Describes a field of a struct sequence. As a struct sequence is modeled as a
|
||||
tuple, all fields are typed as :c:type:`PyObject\*`. The index in the
|
||||
:attr:`fields` array of the :c:type:`PyStructSequence_Desc` determines which
|
||||
field of the struct sequence is described.
|
||||
|
||||
+-----------+------------------+--------------------------------------+
|
||||
| Field | C Type | Meaning |
|
||||
+===========+==================+======================================+
|
||||
| ``name`` | ``const char *`` | name for the field or *NULL* to end |
|
||||
| | | the list of named fields, set to |
|
||||
| | | PyStructSequence_UnnamedField to |
|
||||
| | | leave unnamed |
|
||||
+-----------+------------------+--------------------------------------+
|
||||
| ``doc`` | ``const char *`` | field docstring or *NULL* to omit |
|
||||
+-----------+------------------+--------------------------------------+
|
||||
|
||||
|
||||
.. c:var:: char* PyStructSequence_UnnamedField
|
||||
|
||||
Special value for a field name to leave it unnamed.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyStructSequence_New(PyTypeObject *type)
|
||||
|
||||
Creates an instance of *type*, which must have been created with
|
||||
:c:func:`PyStructSequence_NewType`.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyStructSequence_GetItem(PyObject *p, Py_ssize_t pos)
|
||||
|
||||
Return the object at position *pos* in the struct sequence pointed to by *p*.
|
||||
No bounds checking is performed.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyStructSequence_GET_ITEM(PyObject *p, Py_ssize_t pos)
|
||||
|
||||
Macro equivalent of :c:func:`PyStructSequence_GetItem`.
|
||||
|
||||
|
||||
.. c:function:: void PyStructSequence_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)
|
||||
|
||||
Sets the field at index *pos* of the struct sequence *p* to value *o*. Like
|
||||
:c:func:`PyTuple_SET_ITEM`, this should only be used to fill in brand new
|
||||
instances.
|
||||
|
||||
.. note::
|
||||
|
||||
This function "steals" a reference to *o*.
|
||||
|
||||
|
||||
.. c:function:: void PyStructSequence_SET_ITEM(PyObject *p, Py_ssize_t *pos, PyObject *o)
|
||||
|
||||
Macro equivalent of :c:func:`PyStructSequence_SetItem`.
|
||||
|
||||
.. note::
|
||||
|
||||
This function "steals" a reference to *o*.
|
||||
@ -0,0 +1,118 @@
|
||||
.. 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
|
||||
|
||||
This is the type object for type objects; it is the same object as
|
||||
:class:`type` 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.
|
||||
|
||||
|
||||
.. c:function:: unsigned int PyType_ClearCache()
|
||||
|
||||
Clear the internal lookup cache. Return the current version tag.
|
||||
|
||||
.. c:function:: unsigned long PyType_GetFlags(PyTypeObject* type)
|
||||
|
||||
Return the :c:member:`~PyTypeObject.tp_flags` member of *type*. This function is primarily
|
||||
meant for use with `Py_LIMITED_API`; the individual flag bits are
|
||||
guaranteed to be stable across Python releases, but access to
|
||||
:c:member:`~PyTypeObject.tp_flags` itself is not part of the limited API.
|
||||
|
||||
.. versionadded:: 3.2
|
||||
|
||||
.. versionchanged:: 3.4
|
||||
The return type is now ``unsigned long`` rather than ``long``.
|
||||
|
||||
|
||||
.. 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.
|
||||
|
||||
|
||||
.. c:function:: int PyType_HasFeature(PyTypeObject *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(PyTypeObject *o)
|
||||
|
||||
Return true if the type object includes support for the cycle detector; this
|
||||
tests the type flag :const:`Py_TPFLAGS_HAVE_GC`.
|
||||
|
||||
|
||||
.. c:function:: int PyType_IsSubtype(PyTypeObject *a, PyTypeObject *b)
|
||||
|
||||
Return true if *a* is a subtype of *b*.
|
||||
|
||||
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)
|
||||
|
||||
Generic handler for the :c:member:`~PyTypeObject.tp_alloc` slot of a type object. Use
|
||||
Python's default memory allocation mechanism to allocate a new instance and
|
||||
initialize all its contents to *NULL*.
|
||||
|
||||
.. c:function:: PyObject* PyType_GenericNew(PyTypeObject *type, PyObject *args, PyObject *kwds)
|
||||
|
||||
Generic handler for the :c:member:`~PyTypeObject.tp_new` slot of a type object. Create a
|
||||
new instance using the type's :c:member:`~PyTypeObject.tp_alloc` slot.
|
||||
|
||||
.. 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.
|
||||
|
||||
.. c:function:: PyObject* PyType_FromSpec(PyType_Spec *spec)
|
||||
|
||||
Creates and returns a heap type object from the *spec* passed to the function.
|
||||
|
||||
.. c:function:: PyObject* PyType_FromSpecWithBases(PyType_Spec *spec, PyObject *bases)
|
||||
|
||||
Creates and returns a heap type object from the *spec*. In addition to that,
|
||||
the created heap type contains all types contained by the *bases* tuple as base
|
||||
types. This allows the caller to reference other heap types as base types.
|
||||
|
||||
.. versionadded:: 3.3
|
||||
|
||||
.. c:function:: void* PyType_GetSlot(PyTypeObject *type, int slot)
|
||||
|
||||
Return the function pointer stored in the given slot. If the
|
||||
result is *NULL*, this indicates that either the slot is *NULL*,
|
||||
or that the function was called with invalid parameters.
|
||||
Callers will typically cast the result pointer into the appropriate
|
||||
function type.
|
||||
|
||||
.. versionadded:: 3.4
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@ -0,0 +1,21 @@
|
||||
.. 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
|
||||
@ -0,0 +1,394 @@
|
||||
.. 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, wchar_t **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 (converted to wchar_t according to the user's locale). 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 (i.e., 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`. *filename* is decoded from the filesystem
|
||||
encoding (:func:`sys.getfilesystemencoding`). 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_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, it is decoded from the filesystem encoding
|
||||
(:func:`sys.getfilesystemencoding`). If *closeit* is true, the file is
|
||||
closed before PyRun_SimpleFileExFlags returns.
|
||||
|
||||
.. note::
|
||||
On Windows, *fp* should be opened as binary mode (e.g. ``fopen(filename, "rb")``.
|
||||
Otherwise, Python may not handle script file with LF line ending correctly.
|
||||
|
||||
|
||||
.. 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``. *filename* is decoded from the
|
||||
filesystem encoding (:func:`sys.getfilesystemencoding`).
|
||||
|
||||
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``. *filename* is decoded from the filesystem encoding
|
||||
(:func:`sys.getfilesystemencoding`). Returns ``0`` at EOF or a negative
|
||||
number upon failure.
|
||||
|
||||
|
||||
.. c:var:: int (*PyOS_InputHook)(void)
|
||||
|
||||
Can be set to point to a function with the prototype
|
||||
``int func(void)``. The function will be called when Python's
|
||||
interpreter prompt is about to become idle and wait for user input
|
||||
from the terminal. The return value is ignored. Overriding this
|
||||
hook can be used to integrate the interpreter's prompt with other
|
||||
event loops, as done in the :file:`Modules/_tkinter.c` in the
|
||||
Python source code.
|
||||
|
||||
|
||||
.. c:var:: char* (*PyOS_ReadlineFunctionPointer)(FILE *, FILE *, const char *)
|
||||
|
||||
Can be set to point to a function with the prototype
|
||||
``char *func(FILE *stdin, FILE *stdout, char *prompt)``,
|
||||
overriding the default function used to read a single line of input
|
||||
at the interpreter's prompt. The function is expected to output
|
||||
the string *prompt* if it's not *NULL*, and then read a line of
|
||||
input from the provided standard input file, returning the
|
||||
resulting string. For example, The :mod:`readline` module sets
|
||||
this hook to provide line-editing and tab-completion features.
|
||||
|
||||
The result must be a string allocated by :c:func:`PyMem_RawMalloc` or
|
||||
:c:func:`PyMem_RawRealloc`, or *NULL* if an error occurred.
|
||||
|
||||
.. versionchanged:: 3.4
|
||||
The result must be allocated by :c:func:`PyMem_RawMalloc` or
|
||||
:c:func:`PyMem_RawRealloc`, instead of being allocated by
|
||||
:c:func:`PyMem_Malloc` or :c:func:`PyMem_Realloc`.
|
||||
|
||||
|
||||
.. 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. *filename* is decoded from the filesystem encoding
|
||||
(:func:`sys.getfilesystemencoding`).
|
||||
|
||||
|
||||
.. 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
|
||||
objects *globals* and *locals* with the compiler flags specified by
|
||||
*flags*. *globals* must be a dictionary; *locals* can be any object
|
||||
that implements the mapping protocol. 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,
|
||||
it is decoded from the filesystem encoding (:func:`sys.getfilesystemencoding`).
|
||||
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)
|
||||
|
||||
This is a simplified interface to :c:func:`Py_CompileStringExFlags` below, with
|
||||
*optimize* set to ``-1``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* Py_CompileStringObject(const char *str, PyObject *filename, int start, PyCompilerFlags *flags, int optimize)
|
||||
|
||||
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.
|
||||
|
||||
The integer *optimize* specifies the optimization level of the compiler; a
|
||||
value of ``-1`` selects the optimization level of the interpreter as given by
|
||||
:option:`-O` options. Explicit levels are ``0`` (no optimization;
|
||||
``__debug__`` is true), ``1`` (asserts are removed, ``__debug__`` is false)
|
||||
or ``2`` (docstrings are removed too).
|
||||
|
||||
.. versionadded:: 3.4
|
||||
|
||||
|
||||
.. c:function:: PyObject* Py_CompileStringExFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags, int optimize)
|
||||
|
||||
Like :c:func:`Py_CompileStringObject`, but *filename* is a byte string
|
||||
decoded from the filesystem encoding (:func:`os.fsdecode`).
|
||||
|
||||
.. versionadded:: 3.2
|
||||
|
||||
.. c:function:: PyObject* PyEval_EvalCode(PyObject *co, PyObject *globals, PyObject *locals)
|
||||
|
||||
This is a simplified interface to :c:func:`PyEval_EvalCodeEx`, with just
|
||||
the code object, and global and local variables. The other arguments are
|
||||
set to *NULL*.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyEval_EvalCodeEx(PyObject *co, PyObject *globals, PyObject *locals, PyObject *const *args, int argcount, PyObject *const *kws, int kwcount, PyObject *const *defs, int defcount, PyObject *kwdefs, PyObject *closure)
|
||||
|
||||
Evaluate a precompiled code object, given a particular environment for its
|
||||
evaluation. This environment consists of a dictionary of global variables,
|
||||
a mapping object of local variables, arrays of arguments, keywords and
|
||||
defaults, a dictionary of default values for :ref:`keyword-only
|
||||
<keyword-only_parameter>` arguments and a closure tuple of cells.
|
||||
|
||||
|
||||
.. c:type:: PyFrameObject
|
||||
|
||||
The C structure of the objects used to describe frame objects. The
|
||||
fields of this type are subject to change at any time.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyEval_EvalFrame(PyFrameObject *f)
|
||||
|
||||
Evaluate an execution frame. This is a simplified interface to
|
||||
:c:func:`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.
|
||||
|
||||
.. versionchanged:: 3.4
|
||||
This function now includes a debug assertion to help ensure that it
|
||||
does not silently discard an active exception.
|
||||
|
||||
|
||||
.. 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`.
|
||||
@ -0,0 +1,69 @@
|
||||
.. 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.
|
||||
|
||||
|
||||
.. c:function:: int PyWeakref_CheckRef(ob)
|
||||
|
||||
Return true if *ob* is a reference object.
|
||||
|
||||
|
||||
.. c:function:: int PyWeakref_CheckProxy(ob)
|
||||
|
||||
Return true if *ob* is a proxy object.
|
||||
|
||||
|
||||
.. 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`.
|
||||
|
||||
|
||||
.. 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`.
|
||||
|
||||
|
||||
.. 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`.
|
||||
|
||||
.. note::
|
||||
|
||||
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.
|
||||
@ -0,0 +1,31 @@
|
||||
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
||||
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
|
||||
@ -0,0 +1,19 @@
|
||||
*********
|
||||
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.
|
||||
|
||||
@ -0,0 +1,176 @@
|
||||
.. _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.io/
|
||||
|
||||
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/guides/tool-recommendations/#packaging-tool-recommendations
|
||||
|
||||
.. index::
|
||||
single: Python Package Index (PyPI)
|
||||
single: PyPI; (see Python Package Index (PyPI))
|
||||
|
||||
.. _publishing-python-packages:
|
||||
|
||||
Reading the Python Packaging User Guide
|
||||
=======================================
|
||||
|
||||
The Python Packaging User Guide covers the various key steps and elements
|
||||
involved in creating and publishing a project:
|
||||
|
||||
* `Project structure`_
|
||||
* `Building and packaging the project`_
|
||||
* `Uploading the project to the Python Packaging Index`_
|
||||
|
||||
.. _Project structure: \
|
||||
https://packaging.python.org/tutorials/distributing-packages/
|
||||
.. _Building and packaging the project: \
|
||||
https://packaging.python.org/tutorials/distributing-packages/#packaging-your-project
|
||||
.. _Uploading the project to the Python Packaging Index: \
|
||||
https://packaging.python.org/tutorials/distributing-packages/#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/guides/packaging-binary-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/)
|
||||
File diff suppressed because it is too large
Load Diff
@ -0,0 +1,459 @@
|
||||
.. _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) |
|
||||
| | (:file:`.tar.gz`) | |
|
||||
+-------------+------------------------------+---------+
|
||||
| ``bztar`` | bzipped tar file | |
|
||||
| | (:file:`.tar.bz2`) | |
|
||||
+-------------+------------------------------+---------+
|
||||
| ``xztar`` | xzipped tar file | |
|
||||
| | (:file:`.tar.xz`) | |
|
||||
+-------------+------------------------------+---------+
|
||||
| ``ztar`` | compressed tar file | \(3) |
|
||||
| | (:file:`.tar.Z`) | |
|
||||
+-------------+------------------------------+---------+
|
||||
| ``tar`` | tar file (:file:`.tar`) | |
|
||||
+-------------+------------------------------+---------+
|
||||
| ``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. | |
|
||||
+-------------+------------------------------+---------+
|
||||
|
||||
.. versionchanged:: 3.5
|
||||
Added support for the ``xztar`` format.
|
||||
|
||||
|
||||
Notes:
|
||||
|
||||
(1)
|
||||
default on Unix
|
||||
|
||||
(2)
|
||||
default on Windows
|
||||
|
||||
(3)
|
||||
requires external :program:`compress` utility.
|
||||
|
||||
(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``, ``gztar``, ``bztar``,
|
||||
``xztar``, ``ztar``, 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, gztar, bztar, xztar, ztar, 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 :option:`!--no-user-cfg` option to :file:`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`. Note that creating ``wininst`` binary
|
||||
distributions in only supported on Windows systems.
|
||||
|
||||
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', and 'win-amd64'.
|
||||
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).
|
||||
@ -0,0 +1,104 @@
|
||||
.. _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}
|
||||
|
||||
|
||||
.. _sdist-cmd:
|
||||
|
||||
Creating a source distribution: the :command:`sdist` command
|
||||
============================================================
|
||||
|
||||
.. XXX fragment moved down from above: needs context!
|
||||
|
||||
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.
|
||||
|
||||
.. XXX Windows support not there yet
|
||||
|
||||
.. % \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}}
|
||||
|
||||
|
||||
@ -0,0 +1,142 @@
|
||||
.. _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:
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
[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.
|
||||
|
||||
.. code-block:: shell-session
|
||||
|
||||
$ 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:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
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:
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
[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`:
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
[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.
|
||||
|
||||
@ -0,0 +1,338 @@
|
||||
.. _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'])],
|
||||
)
|
||||
|
||||
Checking a package
|
||||
==================
|
||||
|
||||
The ``check`` command allows you to verify if your package meta-data
|
||||
meet the minimum requirements to build a distribution.
|
||||
|
||||
To run it, just call it using your :file:`setup.py` script. If something is
|
||||
missing, ``check`` will display a warning.
|
||||
|
||||
Let's take an example with a simple script::
|
||||
|
||||
from distutils.core import setup
|
||||
|
||||
setup(name='foobar')
|
||||
|
||||
Running the ``check`` command will display some warnings:
|
||||
|
||||
.. code-block:: shell-session
|
||||
|
||||
$ python setup.py check
|
||||
running check
|
||||
warning: check: missing required meta-data: version, url
|
||||
warning: check: missing meta-data: either (author and author_email) or
|
||||
(maintainer and maintainer_email) must be supplied
|
||||
|
||||
|
||||
If you use the reStructuredText syntax in the ``long_description`` field and
|
||||
`docutils`_ is installed you can check if the syntax is fine with the
|
||||
``check`` command, using the ``restructuredtext`` option.
|
||||
|
||||
For example, if the :file:`setup.py` script is changed like this::
|
||||
|
||||
from distutils.core import setup
|
||||
|
||||
desc = """\
|
||||
My description
|
||||
==============
|
||||
|
||||
This is the description of the ``foobar`` package.
|
||||
"""
|
||||
|
||||
setup(name='foobar', version='1', author='tarek',
|
||||
author_email='tarek@ziade.org',
|
||||
url='http://example.com', long_description=desc)
|
||||
|
||||
Where the long description is broken, ``check`` will be able to detect it
|
||||
by using the :mod:`docutils` parser:
|
||||
|
||||
.. code-block:: shell-session
|
||||
|
||||
$ python setup.py check --restructuredtext
|
||||
running check
|
||||
warning: check: Title underline too short. (line 2)
|
||||
warning: check: Could not finish the parsing.
|
||||
|
||||
Reading the metadata
|
||||
=====================
|
||||
|
||||
The :func:`distutils.core.setup` function provides a command-line interface
|
||||
that allows you to query the metadata fields of a project through the
|
||||
``setup.py`` script of a given project:
|
||||
|
||||
.. code-block:: shell-session
|
||||
|
||||
$ python setup.py --name
|
||||
distribute
|
||||
|
||||
This call reads the ``name`` metadata by running the
|
||||
:func:`distutils.core.setup` function. Although, when a source or binary
|
||||
distribution is created with Distutils, the metadata fields are written
|
||||
in a static file called :file:`PKG-INFO`. When a Distutils-based project is
|
||||
installed in Python, the :file:`PKG-INFO` file is copied alongside the modules
|
||||
and packages of the distribution under :file:`NAME-VERSION-pyX.X.egg-info`,
|
||||
where ``NAME`` is the name of the project, ``VERSION`` its version as defined
|
||||
in the Metadata, and ``pyX.X`` the major and minor version of Python like
|
||||
``2.7`` or ``3.2``.
|
||||
|
||||
You can read back this static file, by using the
|
||||
:class:`distutils.dist.DistributionMetadata` class and its
|
||||
:func:`read_pkg_file` method::
|
||||
|
||||
>>> from distutils.dist import DistributionMetadata
|
||||
>>> metadata = DistributionMetadata()
|
||||
>>> metadata.read_pkg_file(open('distribute-0.6.8-py2.7.egg-info'))
|
||||
>>> metadata.name
|
||||
'distribute'
|
||||
>>> metadata.version
|
||||
'0.6.8'
|
||||
>>> metadata.description
|
||||
'Easily download, build, install, upgrade, and uninstall Python packages'
|
||||
|
||||
Notice that the class can also be instantiated with a metadata file path to
|
||||
loads its values::
|
||||
|
||||
>>> pkg_info_path = 'distribute-0.6.8-py2.7.egg-info'
|
||||
>>> DistributionMetadata(pkg_info_path).name
|
||||
'distribute'
|
||||
|
||||
|
||||
.. % \section{Multiple extension modules}
|
||||
.. % \label{multiple-ext}
|
||||
|
||||
.. % \section{Putting it all together}
|
||||
|
||||
|
||||
.. _docutils: http://docutils.sourceforge.net
|
||||
@ -0,0 +1,96 @@
|
||||
.. _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.
|
||||
|
||||
|
||||
@ -0,0 +1,40 @@
|
||||
.. _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/guides/tool-recommendations/>`__
|
||||
in the Python Packaging User Guide for more information.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:numbered:
|
||||
|
||||
introduction.rst
|
||||
setupscript.rst
|
||||
configfile.rst
|
||||
sourcedist.rst
|
||||
builtdist.rst
|
||||
examples.rst
|
||||
extending.rst
|
||||
commandref.rst
|
||||
apiref.rst
|
||||
@ -0,0 +1,212 @@
|
||||
.. _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 window (: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` 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 NumPy, SciPy, 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.
|
||||
@ -0,0 +1,16 @@
|
||||
:orphan:
|
||||
|
||||
.. _package-index:
|
||||
|
||||
*******************************
|
||||
The Python Package Index (PyPI)
|
||||
*******************************
|
||||
|
||||
The `Python Package Index (PyPI)`_ stores metadata describing distributions
|
||||
packaged with distutils and other publishing tools, as well the distribution
|
||||
archives themselves.
|
||||
|
||||
References to up to date PyPI documentation can be found at
|
||||
:ref:`publishing-python-packages`.
|
||||
|
||||
.. _Python Package Index (PyPI): https://pypi.org
|
||||
@ -0,0 +1,711 @@
|
||||
.. _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 ``optional`` option is a boolean; if it is true,
|
||||
a build failure in the extension will not abort the build process, but
|
||||
instead simply not install the failing extension.
|
||||
|
||||
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:: 3.1
|
||||
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']},
|
||||
)
|
||||
|
||||
|
||||
.. versionchanged:: 3.1
|
||||
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:: 3.1
|
||||
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 | \(4) |
|
||||
| | package | | |
|
||||
+----------------------+---------------------------+-----------------+--------+
|
||||
| ``download_url`` | location where the | URL | |
|
||||
| | package may be downloaded | | |
|
||||
+----------------------+---------------------------+-----------------+--------+
|
||||
| ``classifiers`` | a list of classifiers | list of strings | (6)(7) |
|
||||
+----------------------+---------------------------+-----------------+--------+
|
||||
| ``platforms`` | a list of platforms | list of strings | (6)(8) |
|
||||
+----------------------+---------------------------+-----------------+--------+
|
||||
| ``keywords`` | a list of keywords | list of strings | (6)(8) |
|
||||
+----------------------+---------------------------+-----------------+--------+
|
||||
| ``license`` | license for the package | short string | \(5) |
|
||||
+----------------------+---------------------------+-----------------+--------+
|
||||
|
||||
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)
|
||||
The ``long_description`` field is used by PyPI when you publish a package,
|
||||
to build its project page.
|
||||
|
||||
(5)
|
||||
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``.
|
||||
|
||||
(6)
|
||||
This field must be a list.
|
||||
|
||||
(7)
|
||||
The valid classifiers are listed on
|
||||
`PyPI <https://pypi.org/classifiers>`_.
|
||||
|
||||
(8)
|
||||
To preserve backward compatibility, this field also accepts a string. If
|
||||
you pass a comma-separated string ``'foo, bar'``, it will be converted to
|
||||
``['foo', 'bar']``, Otherwise, it will be converted to a list of one
|
||||
string.
|
||||
|
||||
'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.
|
||||
|
||||
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`` must be specified in a 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',
|
||||
],
|
||||
)
|
||||
|
||||
.. versionchanged:: 3.7
|
||||
:class:`~distutils.core.setup` now warns when ``classifiers``, ``keywords``
|
||||
or ``platforms`` fields are not specified as a list or a string.
|
||||
|
||||
.. _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.
|
||||
@ -0,0 +1,240 @@
|
||||
.. _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`) | |
|
||||
+-----------+-------------------------+---------+
|
||||
| ``xztar`` | xz'ed tar file | |
|
||||
| | (:file:`.tar.xz`) | |
|
||||
+-----------+-------------------------+---------+
|
||||
| ``ztar`` | compressed tar file | \(4) |
|
||||
| | (:file:`.tar.Z`) | |
|
||||
+-----------+-------------------------+---------+
|
||||
| ``tar`` | tar file (:file:`.tar`) | |
|
||||
+-----------+-------------------------+---------+
|
||||
|
||||
.. versionchanged:: 3.5
|
||||
Added support for the ``xztar`` format.
|
||||
|
||||
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. Notice that this format is now
|
||||
pending for deprecation and will be removed in the future versions of Python.
|
||||
|
||||
When using any ``tar`` format (``gztar``, ``bztar``, ``xztar``, ``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 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)
|
||||
|
||||
* Any of the standard README files (:file:`README`, :file:`README.txt`,
|
||||
or :file:`README.rst`), :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:: 3.1
|
||||
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:: 3.1.3
|
||||
:file:`MANIFEST` files start with a comment indicating they are generated.
|
||||
Files without this comment are not overwritten or removed.
|
||||
|
||||
.. versionchanged:: 3.2.2
|
||||
:command:`sdist` will read a :file:`MANIFEST` file if no :file:`MANIFEST.in`
|
||||
exists, like it used to do.
|
||||
|
||||
.. versionchanged:: 3.7
|
||||
:file:`README.rst` is now included in the list of distutils standard READMEs.
|
||||
|
||||
|
||||
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, again we turn to the Distutils' own manifest template:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
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.) There are
|
||||
several other commands available in the manifest template mini-language; see
|
||||
section :ref:`sdist-cmd`.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
.. _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`.
|
||||
@ -0,0 +1,8 @@
|
||||
:orphan:
|
||||
|
||||
***************************************
|
||||
Uploading Packages to the Package Index
|
||||
***************************************
|
||||
|
||||
References to up to date PyPI documentation can be found at
|
||||
:ref:`publishing-python-packages`.
|
||||
@ -0,0 +1,167 @@
|
||||
.. highlightlang:: c
|
||||
|
||||
.. _building:
|
||||
|
||||
*****************************
|
||||
Building C and C++ Extensions
|
||||
*****************************
|
||||
|
||||
A C extension for CPython is a shared library (e.g. a ``.so`` file on Linux,
|
||||
``.pyd`` on Windows), which exports an *initialization function*.
|
||||
|
||||
To be importable, the shared library must be available on :envvar:`PYTHONPATH`,
|
||||
and must be named after the module name, with an appropriate extension.
|
||||
When using distutils, the correct filename is generated automatically.
|
||||
|
||||
The initialization function has the signature:
|
||||
|
||||
.. c:function:: PyObject* PyInit_modulename(void)
|
||||
|
||||
It returns either a fully-initialized module, or a :c:type:`PyModuleDef`
|
||||
instance. See :ref:`initializing-modules` for details.
|
||||
|
||||
.. highlightlang:: python
|
||||
|
||||
For modules with ASCII-only names, the function must be named
|
||||
``PyInit_<modulename>``, with ``<modulename>`` replaced by the name of the
|
||||
module. When using :ref:`multi-phase-initialization`, non-ASCII module names
|
||||
are allowed. In this case, the initialization function name is
|
||||
``PyInitU_<modulename>``, with ``<modulename>`` encoded using Python's
|
||||
*punycode* encoding with hyphens replaced by underscores. In Python::
|
||||
|
||||
def initfunc_name(name):
|
||||
try:
|
||||
suffix = b'_' + name.encode('ascii')
|
||||
except UnicodeEncodeError:
|
||||
suffix = b'U_' + name.encode('punycode').replace(b'-', b'_')
|
||||
return b'PyInit' + suffix
|
||||
|
||||
It is possible to export multiple modules from a single shared library by
|
||||
defining multiple initialization functions. However, importing them requires
|
||||
using symbolic links or a custom importer, because by default only the
|
||||
function corresponding to the filename is found.
|
||||
See the *"Multiple modules in one library"* section in :pep:`489` for details.
|
||||
|
||||
|
||||
.. highlightlang:: c
|
||||
|
||||
Building C and C++ Extensions with distutils
|
||||
============================================
|
||||
|
||||
.. sectionauthor:: Martin v. Löwis <martin@v.loewis.de>
|
||||
|
||||
Extension modules can be built using distutils, which is included in Python.
|
||||
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:: python3
|
||||
|
||||
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 additional 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:`~distutils.core.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:: python3
|
||||
|
||||
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:`~distutils.core.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 :ref:`manifest` 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
|
||||
@ -0,0 +1,336 @@
|
||||
.. 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.
|
||||
|
||||
|
||||
.. 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. ::
|
||||
|
||||
#define PY_SSIZE_T_CLEAN
|
||||
#include <Python.h>
|
||||
|
||||
int
|
||||
main(int argc, char *argv[])
|
||||
{
|
||||
wchar_t *program = Py_DecodeLocale(argv[0], NULL);
|
||||
if (program == NULL) {
|
||||
fprintf(stderr, "Fatal error: cannot decode argv[0]\n");
|
||||
exit(1);
|
||||
}
|
||||
Py_SetProgramName(program); /* optional but recommended */
|
||||
Py_Initialize();
|
||||
PyRun_SimpleString("from time import time,ctime\n"
|
||||
"print('Today is', ctime(time()))\n");
|
||||
if (Py_FinalizeEx() < 0) {
|
||||
exit(120);
|
||||
}
|
||||
PyMem_RawFree(program);
|
||||
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_FinalizeEx` 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 :ref:`compile and link <compiling>` 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 = PyUnicode_DecodeFSDefault(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:`PyUnicode_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 PyLong_FromLong(numargs);
|
||||
}
|
||||
|
||||
static PyMethodDef EmbMethods[] = {
|
||||
{"numargs", emb_numargs, METH_VARARGS,
|
||||
"Return the number of arguments received by the process."},
|
||||
{NULL, NULL, 0, NULL}
|
||||
};
|
||||
|
||||
static PyModuleDef EmbModule = {
|
||||
PyModuleDef_HEAD_INIT, "emb", NULL, -1, EmbMethods,
|
||||
NULL, NULL, NULL, NULL
|
||||
};
|
||||
|
||||
static PyObject*
|
||||
PyInit_emb(void)
|
||||
{
|
||||
return PyModule_Create(&EmbModule);
|
||||
}
|
||||
|
||||
Insert the above code just above the :c:func:`main` function. Also, insert the
|
||||
following two statements before the call to :c:func:`Py_Initialize`::
|
||||
|
||||
numargs = argc;
|
||||
PyImport_AppendInittab("emb", &PyInit_emb);
|
||||
|
||||
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++.
|
||||
|
||||
|
||||
.. _compiling:
|
||||
|
||||
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:`python3-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/python3.4-config --cflags
|
||||
-I/opt/include/python3.4m -I/opt/include/python3.4m -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/python3.4-config --ldflags
|
||||
-L/opt/lib/python3.4/config-3.4m -lpthread -ldl -lutil -lm -lpython3.4m -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:: pycon
|
||||
|
||||
>>> import sysconfig
|
||||
>>> sysconfig.get_config_var('LIBS')
|
||||
'-lpthread -ldl -lutil'
|
||||
>>> sysconfig.get_config_var('LINKFORSHARED')
|
||||
'-Xlinker -export-dynamic'
|
||||
|
||||
|
||||
.. XXX similar documentation for Windows missing
|
||||
File diff suppressed because it is too large
Load Diff
@ -0,0 +1,74 @@
|
||||
.. _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`.
|
||||
|
||||
|
||||
Recommended third party tools
|
||||
=============================
|
||||
|
||||
This guide only covers the basic tools for creating extensions provided
|
||||
as part of this version of CPython. Third party tools like
|
||||
`Cython <http://cython.org/>`_, `cffi <https://cffi.readthedocs.io>`_,
|
||||
`SWIG <http://www.swig.org>`_ and `Numba <https://numba.pydata.org/>`_
|
||||
offer both simpler and more sophisticated approaches to creating C and C++
|
||||
extensions for Python.
|
||||
|
||||
.. seealso::
|
||||
|
||||
`Python Packaging User Guide: Binary Extensions <https://packaging.python.org/guides/packaging-binary-extensions/>`_
|
||||
The Python Packaging User Guide not only covers several available
|
||||
tools that simplify the creation of binary extensions, but also
|
||||
discusses the various reasons why creating an extension module may be
|
||||
desirable in the first place.
|
||||
|
||||
|
||||
Creating extensions without third party tools
|
||||
=============================================
|
||||
|
||||
This section of the guide covers creating C and C++ extensions without
|
||||
assistance from third party tools. It is intended primarily for creators
|
||||
of those tools, rather than being a recommended way to create your own
|
||||
C extensions.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:numbered:
|
||||
|
||||
extending.rst
|
||||
newtypes_tutorial.rst
|
||||
newtypes.rst
|
||||
building.rst
|
||||
windows.rst
|
||||
|
||||
Embedding the CPython runtime in a larger application
|
||||
=====================================================
|
||||
|
||||
Sometimes, rather than creating an extension that runs inside the Python
|
||||
interpreter as the main application, it is desirable to instead embed
|
||||
the CPython runtime inside a larger application. This section covers
|
||||
some of the details involved in doing that successfully.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:numbered:
|
||||
|
||||
embedding.rst
|
||||
@ -0,0 +1,619 @@
|
||||
.. highlightlang:: c
|
||||
|
||||
*****************************************
|
||||
Defining Extension Types: Assorted Topics
|
||||
*****************************************
|
||||
|
||||
.. _dnt-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. It's often easiest to find an example
|
||||
that includes the fields you need and then change the values to suit your new
|
||||
type. ::
|
||||
|
||||
const char *tp_name; /* For printing */
|
||||
|
||||
The name of the type -- as mentioned in the previous chapter, this will appear in
|
||||
various places, almost entirely for diagnostic purposes. Try to choose something
|
||||
that will be helpful in such a situation! ::
|
||||
|
||||
Py_ssize_t 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, tuples) which is where the :c:member:`~PyTypeObject.tp_itemsize` field
|
||||
comes in. This will be dealt with later. ::
|
||||
|
||||
const 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;
|
||||
|
||||
/* This saves the current exception state */
|
||||
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);
|
||||
|
||||
/* This restores the saved exception state */
|
||||
PyErr_Restore(err_type, err_value, err_traceback);
|
||||
|
||||
Py_DECREF(self->my_callback);
|
||||
}
|
||||
Py_TYPE(obj)->tp_free((PyObject*)self);
|
||||
}
|
||||
|
||||
.. note::
|
||||
There are limitations to what you can safely do in a deallocator function.
|
||||
First, if your type supports garbage collection (using :c:member:`~PyTypeObject.tp_traverse`
|
||||
and/or :c:member:`~PyTypeObject.tp_clear`), some of the object's members can have been
|
||||
cleared or finalized by the time :c:member:`~PyTypeObject.tp_dealloc` is called. Second, in
|
||||
:c:member:`~PyTypeObject.tp_dealloc`, your object is in an unstable state: its reference
|
||||
count is equal to zero. Any call to a non-trivial object or API (as in the
|
||||
example above) might end up calling :c:member:`~PyTypeObject.tp_dealloc` again, causing a
|
||||
double free and a crash.
|
||||
|
||||
Starting with Python 3.4, it is recommended not to put any complex
|
||||
finalization code in :c:member:`~PyTypeObject.tp_dealloc`, and instead use the new
|
||||
:c:member:`~PyTypeObject.tp_finalize` type method.
|
||||
|
||||
.. seealso::
|
||||
:pep:`442` explains the new finalization scheme.
|
||||
|
||||
.. index::
|
||||
single: string; object representation
|
||||
builtin: repr
|
||||
|
||||
Object Presentation
|
||||
-------------------
|
||||
|
||||
In Python, there are two ways to generate a textual representation of an object:
|
||||
the :func:`repr` function, and the :func:`str` function. (The :func:`print`
|
||||
function just calls :func:`str`.) These handlers are both optional.
|
||||
|
||||
::
|
||||
|
||||
reprfunc tp_repr;
|
||||
reprfunc tp_str;
|
||||
|
||||
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 PyUnicode_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 PyUnicode_FromFormat("Stringified_newdatatype{{size:%d}}",
|
||||
obj->obj_UnderlyingDatatypePtr->size);
|
||||
}
|
||||
|
||||
|
||||
|
||||
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_getattro; /* PyObject * version */
|
||||
setattrofunc tp_setattro;
|
||||
|
||||
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
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
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*.
|
||||
|
||||
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 {
|
||||
const char *name;
|
||||
int type;
|
||||
int offset;
|
||||
int flags;
|
||||
const 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.
|
||||
|
||||
The following flag constants are defined in :file:`structmember.h`; they may be
|
||||
combined using bitwise-OR.
|
||||
|
||||
+---------------------------+----------------------------------------------+
|
||||
| Constant | Meaning |
|
||||
+===========================+==============================================+
|
||||
| :const:`READONLY` | Never writable. |
|
||||
+---------------------------+----------------------------------------------+
|
||||
| :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: 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. It 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.
|
||||
|
||||
Here is an example::
|
||||
|
||||
static PyObject *
|
||||
newdatatype_getattr(newdatatypeobject *obj, char *name)
|
||||
{
|
||||
if (strcmp(name, "data") == 0)
|
||||
{
|
||||
return PyLong_FromLong(obj->data);
|
||||
}
|
||||
|
||||
PyErr_Format(PyExc_AttributeError,
|
||||
"'%.50s' object has no attribute '%.400s'",
|
||||
tp->tp_name, name);
|
||||
return NULL;
|
||||
}
|
||||
|
||||
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)
|
||||
{
|
||||
PyErr_Format(PyExc_RuntimeError, "Read-only attribute: %s", name);
|
||||
return -1;
|
||||
}
|
||||
|
||||
Object Comparison
|
||||
-----------------
|
||||
|
||||
::
|
||||
|
||||
richcmpfunc tp_richcompare;
|
||||
|
||||
The :c:member:`~PyTypeObject.tp_richcompare` handler is called when comparisons are needed. It is
|
||||
analogous to the :ref:`rich comparison methods <richcmpfuncs>`, like
|
||||
:meth:`__lt__`, and also called by :c:func:`PyObject_RichCompare` and
|
||||
:c:func:`PyObject_RichCompareBool`.
|
||||
|
||||
This function is called with two Python objects and the operator as arguments,
|
||||
where the operator is one of ``Py_EQ``, ``Py_NE``, ``Py_LE``, ``Py_GT``,
|
||||
``Py_LT`` or ``Py_GT``. It should compare the two objects with respect to the
|
||||
specified operator and return ``Py_True`` or ``Py_False`` if the comparison is
|
||||
successful, ``Py_NotImplemented`` to indicate that comparison is not
|
||||
implemented and the other object's comparison method should be tried, or *NULL*
|
||||
if an exception was set.
|
||||
|
||||
Here is a sample implementation, for a datatype that is considered equal if the
|
||||
size of an internal pointer is equal::
|
||||
|
||||
static PyObject *
|
||||
newdatatype_richcmp(PyObject *obj1, PyObject *obj2, int op)
|
||||
{
|
||||
PyObject *result;
|
||||
int c, size1, size2;
|
||||
|
||||
/* code to make sure that both arguments are of type
|
||||
newdatatype omitted */
|
||||
|
||||
size1 = obj1->obj_UnderlyingDatatypePtr->size;
|
||||
size2 = obj2->obj_UnderlyingDatatypePtr->size;
|
||||
|
||||
switch (op) {
|
||||
case Py_LT: c = size1 < size2; break;
|
||||
case Py_LE: c = size1 <= size2; break;
|
||||
case Py_EQ: c = size1 == size2; break;
|
||||
case Py_NE: c = size1 != size2; break;
|
||||
case Py_GT: c = size1 > size2; break;
|
||||
case Py_GE: c = size1 >= size2; break;
|
||||
}
|
||||
result = c ? Py_True : Py_False;
|
||||
Py_INCREF(result);
|
||||
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 simple example::
|
||||
|
||||
static Py_hash_t
|
||||
newdatatype_hash(newdatatypeobject *obj)
|
||||
{
|
||||
Py_hash_t result;
|
||||
result = obj->some_size + 32767 * obj->some_number;
|
||||
if (result == -1)
|
||||
result = -2;
|
||||
return result;
|
||||
}
|
||||
|
||||
:c:type:`Py_hash_t` is a signed integer type with a platform-varying width.
|
||||
Returning ``-1`` from :c:member:`~PyTypeObject.tp_hash` indicates an error,
|
||||
which is why you should be careful to avoid returning it when hash computation
|
||||
is successful, as seen above.
|
||||
|
||||
::
|
||||
|
||||
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:
|
||||
|
||||
#. *self* is the instance of the data type which is the subject of the call.
|
||||
If the call is ``obj1('hello')``, then *self* is ``obj1``.
|
||||
|
||||
#. *args* is a tuple containing the arguments to the call. You can use
|
||||
:c:func:`PyArg_ParseTuple` to extract the arguments.
|
||||
|
||||
#. *kwds* 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 toy ``tp_call`` implementation::
|
||||
|
||||
static PyObject *
|
||||
newdatatype_call(newdatatypeobject *self, PyObject *args, PyObject *kwds)
|
||||
{
|
||||
PyObject *result;
|
||||
const char *arg1;
|
||||
const char *arg2;
|
||||
const char *arg3;
|
||||
|
||||
if (!PyArg_ParseTuple(args, "sss:call", &arg1, &arg2, &arg3)) {
|
||||
return NULL;
|
||||
}
|
||||
result = PyUnicode_FromFormat(
|
||||
"Returning -- value: [%d] arg1: [%s] arg2: [%s] arg3: [%s]\n",
|
||||
obj->obj_UnderlyingDatatypePtr->size,
|
||||
arg1, arg2, arg3);
|
||||
return result;
|
||||
}
|
||||
|
||||
::
|
||||
|
||||
/* Iterators */
|
||||
getiterfunc tp_iter;
|
||||
iternextfunc tp_iternext;
|
||||
|
||||
These functions provide support for the iterator protocol. 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*. :c:member:`~PyTypeObject.tp_iter` corresponds
|
||||
to the Python :meth:`__iter__` method, while :c:member:`~PyTypeObject.tp_iternext`
|
||||
corresponds to the Python :meth:`~iterator.__next__` method.
|
||||
|
||||
Any :term:`iterable` object must implement the :c:member:`~PyTypeObject.tp_iter`
|
||||
handler, which must return an :term:`iterator` object. Here the same guidelines
|
||||
apply as for Python classes:
|
||||
|
||||
* For collections (such as lists and tuples) which can support multiple
|
||||
independent iterators, a new iterator should be created and returned by
|
||||
each call to :c:member:`~PyTypeObject.tp_iter`.
|
||||
* Objects which can only be iterated over once (usually due to side effects of
|
||||
iteration, such as file objects) can implement :c:member:`~PyTypeObject.tp_iter`
|
||||
by returning a new reference to themselves -- and should also therefore
|
||||
implement the :c:member:`~PyTypeObject.tp_iternext` handler.
|
||||
|
||||
Any :term:`iterator` object should implement both :c:member:`~PyTypeObject.tp_iter`
|
||||
and :c:member:`~PyTypeObject.tp_iternext`. An iterator's
|
||||
:c:member:`~PyTypeObject.tp_iter` handler should return a new reference
|
||||
to the iterator. Its :c:member:`~PyTypeObject.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, :c:member:`~PyTypeObject.tp_iternext`
|
||||
may return *NULL* without setting an exception, or it may set
|
||||
:exc:`StopIteration` *in addition* to returning *NULL*; avoiding
|
||||
the exception can yield slightly better performance. If an actual error
|
||||
occurs, :c:member:`~PyTypeObject.tp_iternext` should always 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
|
||||
performance-critical objects (such as numbers).
|
||||
|
||||
.. seealso::
|
||||
Documentation for the :mod:`weakref` module.
|
||||
|
||||
For an object to be weakly referencable, the extension type must do two things:
|
||||
|
||||
#. Include a :c:type:`PyObject\*` field in the C object structure dedicated to
|
||||
the weak reference mechanism. The object's constructor should leave it
|
||||
*NULL* (which is automatic when using the default
|
||||
:c:member:`~PyTypeObject.tp_alloc`).
|
||||
|
||||
#. Set the :c:member:`~PyTypeObject.tp_weaklistoffset` type member
|
||||
to the offset of the aforementioned field in the C object structure,
|
||||
so that the interpreter knows how to access and modify that field.
|
||||
|
||||
Concretely, here is how a trivial object structure would be augmented
|
||||
with the required field::
|
||||
|
||||
typedef struct {
|
||||
PyObject_HEAD
|
||||
PyObject *weakreflist; /* List of weak references */
|
||||
} TrivialObject;
|
||||
|
||||
And the corresponding member in the statically-declared type object::
|
||||
|
||||
static PyTypeObject TrivialType = {
|
||||
PyVarObject_HEAD_INIT(NULL, 0)
|
||||
/* ... other members omitted for brevity ... */
|
||||
.tp_weaklistoffset = offsetof(TrivialObject, weakreflist),
|
||||
};
|
||||
|
||||
The only further addition is that ``tp_dealloc`` needs to clear any weak
|
||||
references (by calling :c:func:`PyObject_ClearWeakRefs`) if the field is
|
||||
non-*NULL*::
|
||||
|
||||
static void
|
||||
Trivial_dealloc(TrivialObject *self)
|
||||
{
|
||||
/* Clear weakrefs first before calling any destructors */
|
||||
if (self->weakreflist != NULL)
|
||||
PyObject_ClearWeakRefs((PyObject *) self);
|
||||
/* ... remainder of destruction code omitted for brevity ... */
|
||||
Py_TYPE(self)->tp_free((PyObject *) self);
|
||||
}
|
||||
|
||||
|
||||
More Suggestions
|
||||
----------------
|
||||
|
||||
In order to learn how to implement any specific method for your new data type,
|
||||
get the :term:`CPython` source code. Go to the :file:`Objects` directory,
|
||||
then search the C source files for ``tp_`` plus the function you want
|
||||
(for example, ``tp_richcompare``). You will find examples of the function
|
||||
you want to implement.
|
||||
|
||||
When you need to verify that an object is a concrete 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;
|
||||
}
|
||||
|
||||
.. seealso::
|
||||
Download CPython source releases.
|
||||
https://www.python.org/downloads/source/
|
||||
|
||||
The CPython project on GitHub, where the CPython source code is developed.
|
||||
https://github.com/python/cpython
|
||||
@ -0,0 +1,897 @@
|
||||
.. highlightlang:: c
|
||||
|
||||
.. _defining-new-types:
|
||||
|
||||
**********************************
|
||||
Defining Extension Types: Tutorial
|
||||
**********************************
|
||||
|
||||
.. sectionauthor:: Michael Hudson <mwh@python.net>
|
||||
.. sectionauthor:: Dave Kuhlman <dkuhlman@rexx.com>
|
||||
.. sectionauthor:: Jim Fulton <jim@zope.com>
|
||||
|
||||
|
||||
Python allows the writer of a C extension module to define new types that
|
||||
can be manipulated from Python code, much like the built-in :class:`str`
|
||||
and :class:`list` types. The code for all extension types follows a
|
||||
pattern, but there are some details that you need to understand before you
|
||||
can get started. This document is a gentle introduction to the topic.
|
||||
|
||||
|
||||
.. _dnt-basics:
|
||||
|
||||
The Basics
|
||||
==========
|
||||
|
||||
The :term:`CPython` runtime sees all Python objects as variables of type
|
||||
:c:type:`PyObject\*`, which serves as a "base type" for all Python objects.
|
||||
The :c:type:`PyObject` structure itself only contains the object's
|
||||
:term:`reference count` and a pointer to the object's "type object".
|
||||
This is where the action is; the type object determines which (C) functions
|
||||
get called by the interpreter when, for instance, an attribute gets looked up
|
||||
on an object, a method called, or it is multiplied by another object. These
|
||||
C functions are called "type methods".
|
||||
|
||||
So, if you want to define a new extension 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 named :class:`Custom` inside a C
|
||||
extension module :mod:`custom`:
|
||||
|
||||
.. note::
|
||||
What we're showing here is the traditional way of defining *static*
|
||||
extension types. It should be adequate for most uses. The C API also
|
||||
allows defining heap-allocated extension types using the
|
||||
:c:func:`PyType_FromSpec` function, which isn't covered in this tutorial.
|
||||
|
||||
.. literalinclude:: ../includes/custom.c
|
||||
|
||||
Now that's quite a bit to take in at once, but hopefully bits will seem familiar
|
||||
from the previous chapter. This file defines three things:
|
||||
|
||||
#. What a :class:`Custom` **object** contains: this is the ``CustomObject``
|
||||
struct, which is allocated once for each :class:`Custom` instance.
|
||||
#. How the :class:`Custom` **type** behaves: this is the ``CustomType`` struct,
|
||||
which defines a set of flags and function pointers that the interpreter
|
||||
inspects when specific operations are requested.
|
||||
#. How to initialize the :mod:`custom` module: this is the ``PyInit_custom``
|
||||
function and the associated ``custommodule`` struct.
|
||||
|
||||
The first bit is::
|
||||
|
||||
typedef struct {
|
||||
PyObject_HEAD
|
||||
} CustomObject;
|
||||
|
||||
This is what a Custom object will contain. ``PyObject_HEAD`` is mandatory
|
||||
at the start of each object struct and defines a field called ``ob_base``
|
||||
of type :c:type:`PyObject`, containing a pointer to a type object and a
|
||||
reference count (these can be accessed using the macros :c:macro:`Py_REFCNT`
|
||||
and :c:macro:`Py_TYPE` respectively). The reason for the macro is to
|
||||
abstract away the layout and to enable additional fields in debug builds.
|
||||
|
||||
.. note::
|
||||
There is no semicolon above after the :c:macro:`PyObject_HEAD` macro.
|
||||
Be wary of adding one by accident: some compilers will complain.
|
||||
|
||||
Of course, objects generally store additional data besides the standard
|
||||
``PyObject_HEAD`` boilerplate; for example, here is the definition for
|
||||
standard Python floats::
|
||||
|
||||
typedef struct {
|
||||
PyObject_HEAD
|
||||
double ob_fval;
|
||||
} PyFloatObject;
|
||||
|
||||
The second bit is the definition of the type object. ::
|
||||
|
||||
static PyTypeObject CustomType = {
|
||||
PyVarObject_HEAD_INIT(NULL, 0)
|
||||
.tp_name = "custom.Custom",
|
||||
.tp_doc = "Custom objects",
|
||||
.tp_basicsize = sizeof(CustomObject),
|
||||
.tp_itemsize = 0,
|
||||
.tp_flags = Py_TPFLAGS_DEFAULT,
|
||||
.tp_new = PyType_GenericNew,
|
||||
};
|
||||
|
||||
.. note::
|
||||
We recommend using C99-style designated initializers as above, to
|
||||
avoid listing all the :c:type:`PyTypeObject` fields that you don't care
|
||||
about and also to avoid caring about the fields' declaration order.
|
||||
|
||||
The actual definition of :c:type:`PyTypeObject` in :file:`object.h` has
|
||||
many more :ref:`fields <type-structs>` than 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.
|
||||
|
||||
We're going to pick it apart, one field at a time::
|
||||
|
||||
PyVarObject_HEAD_INIT(NULL, 0)
|
||||
|
||||
This line is mandatory boilerplate to initialize the ``ob_base``
|
||||
field mentioned above. ::
|
||||
|
||||
.tp_name = "custom.Custom",
|
||||
|
||||
The name of our type. This will appear in the default textual representation of
|
||||
our objects and in some error messages, for example:
|
||||
|
||||
.. code-block:: pycon
|
||||
|
||||
>>> "" + custom.Custom()
|
||||
Traceback (most recent call last):
|
||||
File "<stdin>", line 1, in <module>
|
||||
TypeError: can only concatenate str (not "custom.Custom") to str
|
||||
|
||||
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:`custom` and
|
||||
the type is :class:`Custom`, so we set the type name to :class:`custom.Custom`.
|
||||
Using the real dotted import path is important to make your type compatible
|
||||
with the :mod:`pydoc` and :mod:`pickle` modules. ::
|
||||
|
||||
.tp_basicsize = sizeof(CustomObject),
|
||||
.tp_itemsize = 0,
|
||||
|
||||
This is so that Python knows how much memory to allocate when creating
|
||||
new :class:`Custom` instances. :c:member:`~PyTypeObject.tp_itemsize` is
|
||||
only used for variable-sized objects and should otherwise be zero.
|
||||
|
||||
.. 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.
|
||||
|
||||
We set the class flags to :const:`Py_TPFLAGS_DEFAULT`. ::
|
||||
|
||||
.tp_flags = Py_TPFLAGS_DEFAULT,
|
||||
|
||||
All types should include this constant in their flags. It enables all of the
|
||||
members defined until at least Python 3.3. If you need further members,
|
||||
you will need to OR the corresponding flags.
|
||||
|
||||
We provide a doc string for the type in :c:member:`~PyTypeObject.tp_doc`. ::
|
||||
|
||||
.tp_doc = "Custom objects",
|
||||
|
||||
To enable object creation, we have to provide a :c:member:`~PyTypeObject.tp_new`
|
||||
handler. This is the equivalent of the Python method :meth:`__new__`, but
|
||||
has to be specified explicitly. In this case, we can just use the default
|
||||
implementation provided by the API function :c:func:`PyType_GenericNew`. ::
|
||||
|
||||
.tp_new = PyType_GenericNew,
|
||||
|
||||
Everything else in the file should be familiar, except for some code in
|
||||
:c:func:`PyInit_custom`::
|
||||
|
||||
if (PyType_Ready(&CustomType) < 0)
|
||||
return;
|
||||
|
||||
This initializes the :class:`Custom` type, filling in a number of members
|
||||
to the appropriate default values, including :attr:`ob_type` that we initially
|
||||
set to *NULL*. ::
|
||||
|
||||
PyModule_AddObject(m, "Custom", (PyObject *) &CustomType);
|
||||
|
||||
This adds the type to the module dictionary. This allows us to create
|
||||
:class:`Custom` instances by calling the :class:`Custom` class:
|
||||
|
||||
.. code-block:: pycon
|
||||
|
||||
>>> import custom
|
||||
>>> mycustom = custom.Custom()
|
||||
|
||||
That's it! All that remains is to build it; put the above code in a file called
|
||||
:file:`custom.c` and:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from distutils.core import setup, Extension
|
||||
setup(name="custom", version="1.0",
|
||||
ext_modules=[Extension("custom", ["custom.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:`custom.so` in a subdirectory; move to
|
||||
that directory and fire up Python --- you should be able to ``import custom`` and
|
||||
play around with Custom objects.
|
||||
|
||||
That wasn't so hard, was it?
|
||||
|
||||
Of course, the current Custom type is pretty uninteresting. It has no data and
|
||||
doesn't do anything. It can't even be subclassed.
|
||||
|
||||
.. note::
|
||||
While this documentation showcases the standard :mod:`distutils` module
|
||||
for building C extensions, it is recommended in real-world use cases to
|
||||
use the newer and better-maintained ``setuptools`` library. Documentation
|
||||
on how to do this is out of scope for this document and can be found in
|
||||
the `Python Packaging User's Guide <https://packaging.python.org/tutorials/distributing-packages/>`_.
|
||||
|
||||
|
||||
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:`custom2` that
|
||||
adds these capabilities:
|
||||
|
||||
.. literalinclude:: ../includes/custom2.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 :class:`Custom` type now has three data attributes in its C struct,
|
||||
*first*, *last*, and *number*. The *first* and *last* variables are Python
|
||||
strings containing first and last names. The *number* attribute is a C integer.
|
||||
|
||||
The object structure is updated accordingly::
|
||||
|
||||
typedef struct {
|
||||
PyObject_HEAD
|
||||
PyObject *first; /* first name */
|
||||
PyObject *last; /* last name */
|
||||
int number;
|
||||
} CustomObject;
|
||||
|
||||
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
|
||||
Custom_dealloc(CustomObject *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::
|
||||
|
||||
.tp_dealloc = (destructor) Custom_dealloc,
|
||||
|
||||
This method first clears the reference counts of the two Python attributes.
|
||||
:c:func:`Py_XDECREF` correctly handles the case where its argument is
|
||||
*NULL* (which might happen here if ``tp_new`` failed midway). It then
|
||||
calls the :c:member:`~PyTypeObject.tp_free` member of the object's type
|
||||
(computed by ``Py_TYPE(self)``) to free the object's memory. Note that
|
||||
the object's type might not be :class:`CustomType`, because the object may
|
||||
be an instance of a subclass.
|
||||
|
||||
.. note::
|
||||
The explicit cast to ``destructor`` above is needed because we defined
|
||||
``Custom_dealloc`` to take a ``CustomObject *`` argument, but the ``tp_dealloc``
|
||||
function pointer expects to receive a ``PyObject *`` argument. Otherwise,
|
||||
the compiler will emit a warning. This is object-oriented polymorphism,
|
||||
in C!
|
||||
|
||||
We want to make sure that the first and last names are initialized to empty
|
||||
strings, so we provide a ``tp_new`` implementation::
|
||||
|
||||
static PyObject *
|
||||
Custom_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
|
||||
{
|
||||
CustomObject *self;
|
||||
self = (CustomObject *) type->tp_alloc(type, 0);
|
||||
if (self != NULL) {
|
||||
self->first = PyUnicode_FromString("");
|
||||
if (self->first == NULL) {
|
||||
Py_DECREF(self);
|
||||
return NULL;
|
||||
}
|
||||
self->last = PyUnicode_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::
|
||||
|
||||
.tp_new = Custom_new,
|
||||
|
||||
The ``tp_new`` handler is responsible for creating (as opposed to initializing)
|
||||
objects of the type. It is exposed in Python as the :meth:`__new__` method.
|
||||
It is not required to define a ``tp_new`` member, and indeed many extension
|
||||
types will simply reuse :c:func:`PyType_GenericNew` as done in the first
|
||||
version of the ``Custom`` type above. In this case, we use the ``tp_new``
|
||||
handler to initialize the ``first`` and ``last`` attributes to non-*NULL*
|
||||
default values.
|
||||
|
||||
``tp_new`` is passed the type being instantiated (not necessarily ``CustomType``,
|
||||
if a subclass is instantiated) and any arguments passed when the type was
|
||||
called, and is expected to return the instance created. ``tp_new`` handlers
|
||||
always accept positional and keyword arguments, but they often ignore the
|
||||
arguments, leaving the argument handling to initializer (a.k.a. ``tp_init``
|
||||
in C or ``__init__`` in Python) methods.
|
||||
|
||||
.. note::
|
||||
``tp_new`` shouldn't call ``tp_init`` explicitly, as the interpreter
|
||||
will do it itself.
|
||||
|
||||
The ``tp_new`` implementation calls the :c:member:`~PyTypeObject.tp_alloc`
|
||||
slot to allocate memory::
|
||||
|
||||
self = (CustomObject *) type->tp_alloc(type, 0);
|
||||
|
||||
Since memory allocation may fail, we must check the :c:member:`~PyTypeObject.tp_alloc`
|
||||
result against *NULL* before proceeding.
|
||||
|
||||
.. note::
|
||||
We didn'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
|
||||
strategy.
|
||||
|
||||
.. 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 also define an initialization function which accepts arguments to provide
|
||||
initial values for our instance::
|
||||
|
||||
static int
|
||||
Custom_init(CustomObject *self, PyObject *args, PyObject *kwds)
|
||||
{
|
||||
static char *kwlist[] = {"first", "last", "number", NULL};
|
||||
PyObject *first = NULL, *last = NULL, *tmp;
|
||||
|
||||
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. ::
|
||||
|
||||
.tp_init = (initproc) Custom_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. Initializers always accept positional and keyword arguments,
|
||||
and they should return either ``0`` on success or ``-1`` on error.
|
||||
|
||||
Unlike the ``tp_new`` handler, there is no guarantee that ``tp_init``
|
||||
is called at all (for example, the :mod:`pickle` module by default
|
||||
doesn't call :meth:`__init__` on unpickled instances). It can also 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 attribute values. We might be tempted, for example to assign the
|
||||
``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
|
||||
``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
|
||||
``first`` member; or that destructor could release the
|
||||
:term:`Global interpreter Lock` and let arbitrary code run in other
|
||||
threads that accesses and modifies our object.
|
||||
|
||||
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 neither release
|
||||
the :term:`GIL` nor cause any calls back into our type's code;
|
||||
|
||||
* when decrementing a reference count in a :c:member:`~PyTypeObject.tp_dealloc`
|
||||
handler on a type which doesn't support cyclic garbage collection [#]_.
|
||||
|
||||
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 Custom_members[] = {
|
||||
{"first", T_OBJECT_EX, offsetof(CustomObject, first), 0,
|
||||
"first name"},
|
||||
{"last", T_OBJECT_EX, offsetof(CustomObject, last), 0,
|
||||
"last name"},
|
||||
{"number", T_INT, offsetof(CustomObject, number), 0,
|
||||
"custom number"},
|
||||
{NULL} /* Sentinel */
|
||||
};
|
||||
|
||||
and put the definitions in the :c:member:`~PyTypeObject.tp_members` slot::
|
||||
|
||||
.tp_members = Custom_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:`Custom.name()`, that outputs the objects name as the
|
||||
concatenation of the first and last names. ::
|
||||
|
||||
static PyObject *
|
||||
Custom_name(CustomObject *self)
|
||||
{
|
||||
if (self->first == NULL) {
|
||||
PyErr_SetString(PyExc_AttributeError, "first");
|
||||
return NULL;
|
||||
}
|
||||
if (self->last == NULL) {
|
||||
PyErr_SetString(PyExc_AttributeError, "last");
|
||||
return NULL;
|
||||
}
|
||||
return PyUnicode_FromFormat("%S %S", self->first, self->last);
|
||||
}
|
||||
|
||||
The method is implemented as a C function that takes a :class:`Custom` (or
|
||||
:class:`Custom` 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:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
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 Custom_methods[] = {
|
||||
{"name", (PyCFunction) Custom_name, METH_NOARGS,
|
||||
"Return the name, combining the first and last name"
|
||||
},
|
||||
{NULL} /* Sentinel */
|
||||
};
|
||||
|
||||
(note that we used the :const:`METH_NOARGS` flag to indicate that the method
|
||||
is expecting no arguments other than *self*)
|
||||
|
||||
and assign it to the :c:member:`~PyTypeObject.tp_methods` slot::
|
||||
|
||||
.tp_methods = Custom_methods,
|
||||
|
||||
Finally, we'll make our type usable as a base class for subclassing. 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::
|
||||
|
||||
.tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE,
|
||||
|
||||
We rename :c:func:`PyInit_custom` to :c:func:`PyInit_custom2`, update the
|
||||
module name in the :c:type:`PyModuleDef` struct, and update the full class
|
||||
name in the :c:type:`PyTypeObject` struct.
|
||||
|
||||
Finally, we update our :file:`setup.py` file to build the new module:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from distutils.core import setup, Extension
|
||||
setup(name="custom", version="1.0",
|
||||
ext_modules=[
|
||||
Extension("custom", ["custom.c"]),
|
||||
Extension("custom2", ["custom2.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:`Custom` 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/custom3.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::
|
||||
|
||||
static PyObject *
|
||||
Custom_getfirst(CustomObject *self, void *closure)
|
||||
{
|
||||
Py_INCREF(self->first);
|
||||
return self->first;
|
||||
}
|
||||
|
||||
static int
|
||||
Custom_setfirst(CustomObject *self, PyObject *value, void *closure)
|
||||
{
|
||||
PyObject *tmp;
|
||||
if (value == NULL) {
|
||||
PyErr_SetString(PyExc_TypeError, "Cannot delete the first attribute");
|
||||
return -1;
|
||||
}
|
||||
if (!PyUnicode_Check(value)) {
|
||||
PyErr_SetString(PyExc_TypeError,
|
||||
"The first attribute value must be a string");
|
||||
return -1;
|
||||
}
|
||||
tmp = self->first;
|
||||
Py_INCREF(value);
|
||||
self->first = value;
|
||||
Py_DECREF(tmp);
|
||||
return 0;
|
||||
}
|
||||
|
||||
The getter function is passed a :class:`Custom` object and a "closure", which is
|
||||
a 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:`Custom` 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 its
|
||||
new value is not a string.
|
||||
|
||||
We create an array of :c:type:`PyGetSetDef` structures::
|
||||
|
||||
static PyGetSetDef Custom_getsetters[] = {
|
||||
{"first", (getter) Custom_getfirst, (setter) Custom_setfirst,
|
||||
"first name", NULL},
|
||||
{"last", (getter) Custom_getlast, (setter) Custom_setlast,
|
||||
"last name", NULL},
|
||||
{NULL} /* Sentinel */
|
||||
};
|
||||
|
||||
and register it in the :c:member:`~PyTypeObject.tp_getset` slot::
|
||||
|
||||
.tp_getset = Custom_getsetters,
|
||||
|
||||
The last item in a :c:type:`PyGetSetDef` structure is the "closure" mentioned
|
||||
above. In this case, we aren't using a closure, so we just pass *NULL*.
|
||||
|
||||
We also remove the member definitions for these attributes::
|
||||
|
||||
static PyMemberDef Custom_members[] = {
|
||||
{"number", T_INT, offsetof(CustomObject, number), 0,
|
||||
"custom number"},
|
||||
{NULL} /* Sentinel */
|
||||
};
|
||||
|
||||
We also need to update the :c:member:`~PyTypeObject.tp_init` handler to only
|
||||
allow strings [#]_ to be passed::
|
||||
|
||||
static int
|
||||
Custom_init(CustomObject *self, PyObject *args, PyObject *kwds)
|
||||
{
|
||||
static char *kwlist[] = {"first", "last", "number", NULL};
|
||||
PyObject *first = NULL, *last = NULL, *tmp;
|
||||
|
||||
if (!PyArg_ParseTupleAndKeywords(args, kwds, "|UUi", 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 ``first`` and ``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 ``tp_dealloc`` implementation, where there is the possibility that the
|
||||
initialization of these members failed in ``tp_new``.
|
||||
|
||||
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 :term:`cyclic garbage collector (GC) <garbage collection>` 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:
|
||||
|
||||
.. code-block:: pycon
|
||||
|
||||
>>> 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:`Custom` example, we allowed any kind of
|
||||
object to be stored in the :attr:`first` or :attr:`last` attributes [#]_.
|
||||
Besides, in the second and third versions, we allowed subclassing
|
||||
:class:`Custom`, and subclasses may add arbitrary attributes. For any of
|
||||
those two reasons, :class:`Custom` objects can participate in cycles:
|
||||
|
||||
.. code-block:: pycon
|
||||
|
||||
>>> import custom3
|
||||
>>> class Derived(custom3.Custom): pass
|
||||
...
|
||||
>>> n = Derived()
|
||||
>>> n.some_attribute = n
|
||||
|
||||
To allow a :class:`Custom` instance participating in a reference cycle to
|
||||
be properly detected and collected by the cyclic GC, our :class:`Custom` type
|
||||
needs to fill two additional slots and to enable a flag that enables these slots:
|
||||
|
||||
.. literalinclude:: ../includes/custom4.c
|
||||
|
||||
|
||||
First, the traversal method lets the cyclic GC know about subobjects that could
|
||||
participate in cycles::
|
||||
|
||||
static int
|
||||
Custom_traverse(CustomObject *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 provides a :c:func:`Py_VISIT` macro that automates calling visit
|
||||
functions. With :c:func:`Py_VISIT`, we can minimize the amount of boilerplate
|
||||
in ``Custom_traverse``::
|
||||
|
||||
static int
|
||||
Custom_traverse(CustomObject *self, visitproc visit, void *arg)
|
||||
{
|
||||
Py_VISIT(self->first);
|
||||
Py_VISIT(self->last);
|
||||
return 0;
|
||||
}
|
||||
|
||||
.. note::
|
||||
The :c:member:`~PyTypeObject.tp_traverse` implementation must name its
|
||||
arguments exactly *visit* and *arg* in order to use :c:func:`Py_VISIT`.
|
||||
|
||||
Second, we need to provide a method for clearing any subobjects that can
|
||||
participate in cycles::
|
||||
|
||||
static int
|
||||
Custom_clear(CustomObject *self)
|
||||
{
|
||||
Py_CLEAR(self->first);
|
||||
Py_CLEAR(self->last);
|
||||
return 0;
|
||||
}
|
||||
|
||||
Notice the use of the :c:func:`Py_CLEAR` macro. It is the recommended and safe
|
||||
way to clear data attributes of arbitrary types while decrementing
|
||||
their reference counts. If you were to call :c:func:`Py_XDECREF` instead
|
||||
on the attribute before setting it to *NULL*, there is a possibility
|
||||
that the attribute's destructor would call back into code that reads the
|
||||
attribute again (*especially* if there is a reference cycle).
|
||||
|
||||
.. note::
|
||||
You could emulate :c:func:`Py_CLEAR` by writing::
|
||||
|
||||
PyObject *tmp;
|
||||
tmp = self->first;
|
||||
self->first = NULL;
|
||||
Py_XDECREF(tmp);
|
||||
|
||||
Nevertheless, it is much easier and less error-prone to always
|
||||
use :c:func:`Py_CLEAR` when deleting an attribute. Don't
|
||||
try to micro-optimize at the expense of robustness!
|
||||
|
||||
The deallocator ``Custom_dealloc`` may call arbitrary code when clearing
|
||||
attributes. It means the circular GC can be triggered inside the function.
|
||||
Since the GC assumes reference count is not zero, we need to untrack the object
|
||||
from the GC by calling :c:func:`PyObject_GC_UnTrack` before clearing members.
|
||||
Here is our reimplemented deallocator using :c:func:`PyObject_GC_UnTrack`
|
||||
and ``Custom_clear``::
|
||||
|
||||
static void
|
||||
Custom_dealloc(CustomObject *self)
|
||||
{
|
||||
PyObject_GC_UnTrack(self);
|
||||
Custom_clear(self);
|
||||
Py_TYPE(self)->tp_free((PyObject *) self);
|
||||
}
|
||||
|
||||
Finally, we add the :const:`Py_TPFLAGS_HAVE_GC` flag to the class flags::
|
||||
|
||||
.tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC,
|
||||
|
||||
That's pretty much it. If we had written custom :c:member:`~PyTypeObject.tp_alloc` or
|
||||
:c:member:`~PyTypeObject.tp_free` handlers, 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 :c:type:`PyTypeObject` it needs. It can be difficult to share
|
||||
these :c:type:`PyTypeObject` structures between extension modules.
|
||||
|
||||
In this example we will create a :class:`SubList` 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:
|
||||
|
||||
.. code-block:: pycon
|
||||
|
||||
>>> import sublist
|
||||
>>> s = sublist.SubList(range(3))
|
||||
>>> s.extend(s)
|
||||
>>> print(len(s))
|
||||
6
|
||||
>>> print(s.increment())
|
||||
1
|
||||
>>> print(s.increment())
|
||||
2
|
||||
|
||||
.. literalinclude:: ../includes/sublist.c
|
||||
|
||||
|
||||
As you can see, the source code closely resembles the :class:`Custom` examples in
|
||||
previous sections. We will break down the main differences between them. ::
|
||||
|
||||
typedef struct {
|
||||
PyListObject list;
|
||||
int state;
|
||||
} SubListObject;
|
||||
|
||||
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:`SubList` instance, its ``PyObject *`` pointer
|
||||
can be safely cast to both ``PyListObject *`` and ``SubListObject *``::
|
||||
|
||||
static int
|
||||
SubList_init(SubListObject *self, PyObject *args, PyObject *kwds)
|
||||
{
|
||||
if (PyList_Type.tp_init((PyObject *) self, args, kwds) < 0)
|
||||
return -1;
|
||||
self->state = 0;
|
||||
return 0;
|
||||
}
|
||||
|
||||
We see above how to call through to the :attr:`__init__` method of the base
|
||||
type.
|
||||
|
||||
This pattern is important when writing a type with custom
|
||||
:c:member:`~PyTypeObject.tp_new` and :c:member:`~PyTypeObject.tp_dealloc`
|
||||
members. The :c:member:`~PyTypeObject.tp_new` handler should not actually
|
||||
create the memory for the object with its :c:member:`~PyTypeObject.tp_alloc`,
|
||||
but let the base class handle it by calling its own :c:member:`~PyTypeObject.tp_new`.
|
||||
|
||||
The :c:type:`PyTypeObject` struct supports a :c:member:`~PyTypeObject.tp_base`
|
||||
specifying the type's concrete base class. Due to cross-platform compiler
|
||||
issues, you can't fill that field directly with a reference to
|
||||
:c:type:`PyList_Type`; it should be done later in the module initialization
|
||||
function::
|
||||
|
||||
PyMODINIT_FUNC
|
||||
PyInit_sublist(void)
|
||||
{
|
||||
PyObject* m;
|
||||
SubListType.tp_base = &PyList_Type;
|
||||
if (PyType_Ready(&SubListType) < 0)
|
||||
return NULL;
|
||||
|
||||
m = PyModule_Create(&sublistmodule);
|
||||
if (m == NULL)
|
||||
return NULL;
|
||||
|
||||
Py_INCREF(&SubListType);
|
||||
PyModule_AddObject(m, "SubList", (PyObject *) &SubListType);
|
||||
return m;
|
||||
}
|
||||
|
||||
Before calling :c:func:`PyType_Ready`, the type structure must have the
|
||||
:c:member:`~PyTypeObject.tp_base` slot filled in. When we are deriving an
|
||||
existing type, it is not necessary to fill out the :c:member:`~PyTypeObject.tp_alloc`
|
||||
slot with :c:func:`PyType_GenericNew` -- the allocation 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:`Custom` examples.
|
||||
|
||||
|
||||
.. 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.
|
||||
|
||||
.. [#] 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.
|
||||
|
||||
.. [#] Also, even with our attributes restricted to strings instances, the user
|
||||
could pass arbitrary :class:`str` subclasses and therefore still create
|
||||
reference cycles.
|
||||
@ -0,0 +1,137 @@
|
||||
.. 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.
|
||||
|
||||
@ -0,0 +1,808 @@
|
||||
======================
|
||||
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?
|
||||
--------------------------------------------------
|
||||
|
||||
Users are often surprised by results like this::
|
||||
|
||||
>>> 1.2 - 1.0
|
||||
0.19999999999999996
|
||||
|
||||
and think it is a bug in Python. It's not. This has little to do with Python,
|
||||
and much more to do with how the underlying platform handles floating-point
|
||||
numbers.
|
||||
|
||||
The :class:`float` type in CPython uses a C ``double`` for storage. A
|
||||
:class:`float` object's value is stored in binary floating-point with a fixed
|
||||
precision (typically 53 bits) and Python uses C operations, which in turn rely
|
||||
on the hardware implementation in the processor, to perform floating-point
|
||||
operations. This means that as far as floating-point operations are concerned,
|
||||
Python behaves like many popular languages including C and Java.
|
||||
|
||||
Many numbers that can be written easily in decimal notation cannot be expressed
|
||||
exactly in binary floating-point. For example, after::
|
||||
|
||||
>>> x = 1.2
|
||||
|
||||
the value stored for ``x`` is a (very good) approximation to the decimal value
|
||||
``1.2``, but is not exactly equal to it. On a typical machine, the actual
|
||||
stored value is::
|
||||
|
||||
1.0011001100110011001100110011001100110011001100110011 (binary)
|
||||
|
||||
which is exactly::
|
||||
|
||||
1.1999999999999999555910790149937383830547332763671875 (decimal)
|
||||
|
||||
The typical precision of 53 bits provides Python floats with 15--16
|
||||
decimal digits of accuracy.
|
||||
|
||||
For a fuller explanation, please see the :ref:`floating point arithmetic
|
||||
<tut-fp-issues>` chapter in the Python tutorial.
|
||||
|
||||
|
||||
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, :term:`file objects
|
||||
<file object>` support the iterator protocol, so you can 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).
|
||||
|
||||
: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.
|
||||
Similar methods exist for bytes and bytearray objects.
|
||||
|
||||
|
||||
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)
|
||||
|
||||
For this specific case, you could also use ``value = dict.setdefault(key,
|
||||
getvalue(key))``, but only if the ``getvalue()`` call is cheap enough because it
|
||||
is evaluated in all cases.
|
||||
|
||||
|
||||
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 <https://github.com/stackless-dev/stackless/wiki>`_,
|
||||
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 implementation of Python, :term:`CPython`, 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.
|
||||
|
||||
Other implementations (such as `Jython <http://www.jython.org>`_ or
|
||||
`PyPy <http://www.pypy.org>`_), however, can rely on a different mechanism
|
||||
such as a full-blown garbage collector. This difference can cause some
|
||||
subtle porting problems if your Python code depends on the behavior of the
|
||||
reference counting implementation.
|
||||
|
||||
In some Python implementations, the following code (which is fine in CPython)
|
||||
will probably run out of file descriptors::
|
||||
|
||||
for file in very_long_list_of_files:
|
||||
f = open(file)
|
||||
c = f.read(1)
|
||||
|
||||
Indeed, using CPython's reference counting and destructor scheme, each new
|
||||
assignment to *f* closes the previous file. With a traditional GC, however,
|
||||
those file objects will only get collected (and closed) at varying and possibly
|
||||
long intervals.
|
||||
|
||||
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 memory management scheme::
|
||||
|
||||
for file in very_long_list_of_files:
|
||||
with open(file) as f:
|
||||
c = f.read(1)
|
||||
|
||||
|
||||
Why doesn't CPython 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, CPython works with anything that
|
||||
implements malloc() and free() properly.
|
||||
|
||||
|
||||
Why isn't all memory freed when CPython 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 and a per-process seed; for example, "Python" could hash to
|
||||
-539294296 while "python", a string that differs by a single bit, could hash
|
||||
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 Big-O notation -- to retrieve a key.
|
||||
|
||||
|
||||
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 :exc:`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.
|
||||
|
||||
If you want to return a new list, use the built-in :func:`sorted` function
|
||||
instead. 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.abc` module defines a set of useful ABCs such as
|
||||
:class:`~collections.abc.Iterable`, :class:`~collections.abc.Container`, and
|
||||
:class:`~collections.abc.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(Exception): 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.
|
||||
@ -0,0 +1,447 @@
|
||||
=======================
|
||||
Extending/Embedding FAQ
|
||||
=======================
|
||||
|
||||
.. only:: html
|
||||
|
||||
.. contents::
|
||||
|
||||
.. highlight:: c
|
||||
|
||||
|
||||
.. XXX need review for Python 3.
|
||||
|
||||
|
||||
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
|
||||
|
||||
`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. Cython and Pyrex make 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 :exc:`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 bytes, :c:func:`PyBytes_Size` returns its length and
|
||||
:c:func:`PyBytes_AsStringAndSize` provides a pointer to its value and its
|
||||
length. Note that Python bytes objects 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:`PyBytes_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 such as numbers (:c:func:`PyNumber_Index` et
|
||||
al.) and mappings in the PyMapping APIs.
|
||||
|
||||
|
||||
How do I use Py_BuildValue() to create a tuple of arbitrary length?
|
||||
-------------------------------------------------------------------
|
||||
|
||||
You can't. Use :c:func:`PyTuple_Pack` instead.
|
||||
|
||||
|
||||
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, const char *method_name,
|
||||
const 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 :class:`io.StringIO` class:
|
||||
|
||||
.. code-block:: pycon
|
||||
|
||||
>>> import io, sys
|
||||
>>> sys.stdout = io.StringIO()
|
||||
>>> print('foo')
|
||||
>>> print('hello world!')
|
||||
>>> sys.stderr.write(sys.stdout.getvalue())
|
||||
foo
|
||||
hello world!
|
||||
|
||||
A custom object to do the same would look like this:
|
||||
|
||||
.. code-block:: pycon
|
||||
|
||||
>>> import io, sys
|
||||
>>> class StdoutCatcher(io.TextIOBase):
|
||||
... def __init__(self):
|
||||
... self.data = []
|
||||
... def write(self, stuff):
|
||||
... self.data.append(stuff)
|
||||
...
|
||||
>>> import sys
|
||||
>>> sys.stdout = StdoutCatcher()
|
||||
>>> print('foo')
|
||||
>>> print('hello world!')
|
||||
>>> sys.stderr.write(''.join(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``.
|
||||
|
||||
|
||||
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::
|
||||
|
||||
#define PY_SSIZE_T_CLEAN
|
||||
#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>
|
||||
|
||||
#define PY_SSIZE_T_CLEAN
|
||||
#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 (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).
|
||||
@ -0,0 +1,446 @@
|
||||
: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
|
||||
Windows 2000 and later.
|
||||
|
||||
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://devguide.python.org/setup/>`__ 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://devguide.python.org/>`_ 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://devguide.python.org/>`_.
|
||||
|
||||
|
||||
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 and is managed
|
||||
by the Python Infrastructure Team. Details `here <http://infra.psf.io>`__.
|
||||
|
||||
|
||||
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 versions
|
||||
of Python: 2.x and 3.x. The recommended version is 3.x, which is supported by
|
||||
most widely used libraries. Although 2.x is still widely used, `it will not
|
||||
be maintained after January 1, 2020 <https://www.python.org/dev/peps/pep-0373/>`_.
|
||||
|
||||
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__',
|
||||
'__dir__', '__doc__', '__eq__', '__format__', '__ge__',
|
||||
'__getattribute__', '__getitem__', '__gt__', '__hash__', '__iadd__',
|
||||
'__imul__', '__init__', '__iter__', '__le__', '__len__', '__lt__',
|
||||
'__mul__', '__ne__', '__new__', '__reduce__', '__reduce_ex__',
|
||||
'__repr__', '__reversed__', '__rmul__', '__setattr__', '__setitem__',
|
||||
'__sizeof__', '__str__', '__subclasshook__', 'append', 'clear',
|
||||
'copy', 'count', 'extend', 'index', 'insert', 'pop', 'remove',
|
||||
'reverse', 'sort']
|
||||
>>> [d for d in dir(L) if '__' not in d]
|
||||
['append', 'clear', 'copy', 'count', 'extend', 'index', 'insert', 'pop', 'remove', 'reverse', 'sort']
|
||||
|
||||
>>> help(L.append)
|
||||
Help on built-in function append:
|
||||
<BLANKLINE>
|
||||
append(...)
|
||||
L.append(object) -> None -- append object to end
|
||||
<BLANKLINE>
|
||||
>>> L.append(1)
|
||||
>>> L
|
||||
[1]
|
||||
|
||||
With the interpreter, documentation is never far from the student as they are
|
||||
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>`_.
|
||||
@ -0,0 +1,159 @@
|
||||
:tocdepth: 2
|
||||
|
||||
==========================
|
||||
Graphic User Interface FAQ
|
||||
==========================
|
||||
|
||||
.. only:: html
|
||||
|
||||
.. contents::
|
||||
|
||||
.. XXX need review for Python 3.
|
||||
|
||||
|
||||
General GUI Questions
|
||||
=====================
|
||||
|
||||
What platform-independent GUI toolkits exist for Python?
|
||||
========================================================
|
||||
|
||||
Depending on what platform(s) you are aiming at, there are several. Some
|
||||
of them haven't been ported to Python 3 yet. At least `Tkinter`_ and `Qt`_
|
||||
are known to be Python 3-compatible.
|
||||
|
||||
.. XXX check links
|
||||
|
||||
Tkinter
|
||||
-------
|
||||
|
||||
Standard builds of Python include an object-oriented interface to the Tcl/Tk
|
||||
widget set, called :ref:`tkinter <Tkinter>`. This is probably the easiest to
|
||||
install (since it comes included with most
|
||||
`binary distributions <https://www.python.org/downloads/>`_ of Python) and use.
|
||||
For more info about Tk, including pointers to the source, see the
|
||||
`Tcl/Tk home page <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 <https://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+
|
||||
----
|
||||
|
||||
The `GObject introspection bindings <https://wiki.gnome.org/Projects/PyGObject>`_
|
||||
for Python allow you to write GTK+ 3 applications. There is also a
|
||||
`Python GTK+ 3 Tutorial <https://python-gtk-3-tutorial.readthedocs.io>`_.
|
||||
|
||||
The older PyGtk bindings for the `Gtk+ 2 toolkit <https://www.gtk.org>`_ have
|
||||
been implemented by James Henstridge; see <http://www.pygtk.org>.
|
||||
|
||||
Kivy
|
||||
----
|
||||
|
||||
`Kivy <https://kivy.org/>`_ is a cross-platform GUI library supporting both
|
||||
desktop operating systems (Windows, macOS, Linux) and mobile devices (Android,
|
||||
iOS). It is written in Python and Cython, and can use a range of windowing
|
||||
backends.
|
||||
|
||||
Kivy is free and open source software distributed under the MIT license.
|
||||
|
||||
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://pypi.org/project/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).
|
||||
@ -0,0 +1,17 @@
|
||||
.. _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
|
||||
@ -0,0 +1,53 @@
|
||||
=============================================
|
||||
"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. There are many such applications,
|
||||
from GUI programs to network servers and administrative scripts.
|
||||
* 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.
|
||||
* Many Unix-compatible operating systems, such as Mac OS X and some Linux
|
||||
distributions, have Python installed by default; 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.
|
||||
|
||||
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in New Issue