Re: [Python-Dev] Document C API that is not part of the limited API

[Nick Coghlan]

On 29 December 2016 at 06:41, Steve Dower  wrote:

> On 28Dec2016 1145, Brett Cannon wrote:
>
>> On Tue, 27 Dec 2016 at 12:15 Ronald Oussoren > > wrote:
>> A directive would make it easier to ensure that the text about the
>> stable API is consistent.  I’d also consider adding that directive
>> to all API’s that *are* part of the stable API instead of the other
>> way around (that would also require changes to …/stable.html). That
>> would have two advantages: firstly it makes it easier to document
>> from which version an API is part of the stable ABI, and secondly
>> forgetting the annotation would imply that an API is not part of the
>> stable ABI instead of accidentally claiming to increase the stable
>> ABI.
>>
>>
>> I like Ronald's suggestion of both using a directive and making it for
>> the stable ABI since it should be an opt-in thing for the API to be
>> stable instead of opt-out.
>>
>
> The directive is a good idea, but I'm a little concerned about the stable
> API being opt-out in the headers and opt-in in the documentation.
>
> Perhaps we should also figure out the preprocessor gymnastics we need to
> make it opt-in in the headers too? Though once we get the build validation
> to detect when the stable API changes accidentally it'll be less of an
> issue.
>

Making it opt-in in the documentation could make the build validation
easier: check the list from the *docs* against the actual symbols being
exported by the headers.

That would have a few benefits:

- if you accidentally add a new function to the stable ABI, you get a test
failure
- if you deliberately add a new function to the stable ABI, but forget to
document it as such, you get a test failure
- if the stable ABI version added directive in the docs doesn't match the
stable ABI version used in the headers, you get a test failure

(That suggests the tests would need to check the headers with all stable
ABI versions from 3.2 up to the current release and ensure they match the
current C API documentation)

Cheers,
Nick.

-- 
Nick Coghlan   |   ncogh...@gmail.com   |   Brisbane, Australia
___
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

[Python-Dev] Summary of Python tracker Issues

[Python tracker]

ACTIVITY SUMMARY (2016-12-23 - 2016-12-30)
Python tracker at http://bugs.python.org/

To view or respond to any of the issues listed below, click on the issue.
Do NOT respond to this message.

Issues counts and deltas:
  open5663 (+11)
  closed 35208 (+49)
  total  40871 (+60)

Open issues with patches: 2449 


Issues opened (32)
==

#28871: Destructor of ElementTree.Element is recursive
http://bugs.python.org/issue28871  reopened by haypo

#29057: Compiler failure on Mac OS X - sys/random.h
http://bugs.python.org/issue29057  opened by Pam.McANulty

#29058: Mark new limited C API
http://bugs.python.org/issue29058  opened by serhiy.storchaka

#29059: Windows: Python not using ANSI compatible console
http://bugs.python.org/issue29059  opened by joseph.hackman

#29062: hashlib documentation link error
http://bugs.python.org/issue29062  opened by frankmillman

#29063: Fixed timemodule compile warnings.
http://bugs.python.org/issue29063  opened by Decorater

#29067: Source archive: wrong directory attributes
http://bugs.python.org/issue29067  opened by amig

#29070: Integration tests for pty.spawn on Linux and all other platfor
http://bugs.python.org/issue29070  opened by Cornelius Diekmann

#29075: Remove Windows Vista support
http://bugs.python.org/issue29075  opened by steve.dower

#29076: Python 3.6 installer doesn't update "python3" shell command
http://bugs.python.org/issue29076  opened by elias

#29077: build failure when enabling dtrace on FreeBSD
http://bugs.python.org/issue29077  opened by swills

#29081: time.strptime() return wrong result
http://bugs.python.org/issue29081  opened by hywl51

#29082: In 2.7.13, _ctypes.LoadLibrary no longer accepts Unicode objec
http://bugs.python.org/issue29082  opened by Chi Hsuan Yen

#29083: Readd PyArg_VaParse to the stable API
http://bugs.python.org/issue29083  opened by serhiy.storchaka

#29084: C API of OrderedDict
http://bugs.python.org/issue29084  opened by serhiy.storchaka

#29086: Document C API that is not part of the limited API
http://bugs.python.org/issue29086  opened by serhiy.storchaka

#29090: python34.dll crash
http://bugs.python.org/issue29090  opened by MikeH

#29092: Sync os.stat's doc and doc string
http://bugs.python.org/issue29092  opened by xiang.zhang

#29093: Windows launcher breaks history in Git Bash
http://bugs.python.org/issue29093  opened by evan_

#29094: Regression in zipfile writing in 2.7.13
http://bugs.python.org/issue29094  opened by Peter Ebden

#29096: Signal Handlers reliably cause UnboundLocalErrors
http://bugs.python.org/issue29096  opened by Ted Meyer

#29097: datetime.fromtimestamp(t) when 0 <= t <= 86399 fails on Python
http://bugs.python.org/issue29097  opened by pekka.klarck

#29098: document minimum sqlite version
http://bugs.python.org/issue29098  opened by carlwgeorge

#29099: sqlite3 timestamp converter cannot handle timezone
http://bugs.python.org/issue29099  opened by bozo.kopic

#29100: Core dump / OverflowError for datetime.fromtimestamp with over
http://bugs.python.org/issue29100  opened by Jordon Phillips

#29102: Add an id field to PyInterpreterState.
http://bugs.python.org/issue29102  opened by eric.snow

#29104: Left bracket remains in format string result when '\' preceeds
http://bugs.python.org/issue29104  opened by Jim Fasarakis-Hilliard

#29105: code or doc improvement for logging.handlers.RotatingFileHandl
http://bugs.python.org/issue29105  opened by redstone-cold

#29107: traceback module incorrectly formats args-less syntax errors
http://bugs.python.org/issue29107  opened by Naftali.Harris

#29108: Python 3.6.0 multiprocessing map_async callback
http://bugs.python.org/issue29108  opened by Jose Miguel Colella

#29110: [patch] Fix file object leak in `aifc.open` when given invalid
http://bugs.python.org/issue29110  opened by azhang

#29113: modulefinder no longer finds all required modules for Python i
http://bugs.python.org/issue29113  opened by adamwill



Most recent 15 issues with no replies (15)
==

#29113: modulefinder no longer finds all required modules for Python i
http://bugs.python.org/issue29113

#29110: [patch] Fix file object leak in `aifc.open` when given invalid
http://bugs.python.org/issue29110

#29107: traceback module incorrectly formats args-less syntax errors
http://bugs.python.org/issue29107

#29105: code or doc improvement for logging.handlers.RotatingFileHandl
http://bugs.python.org/issue29105

#29100: Core dump / OverflowError for datetime.fromtimestamp with over
http://bugs.python.org/issue29100

#29098: document minimum sqlite version
http://bugs.python.org/issue29098

#29094: Regression in zipfile writing in 2.7.13
http://bugs.python.org/issue29094

#29092: Sync os.stat's doc and doc string
http://bugs.python.org/issue29092

#29086: Document C API that is not part of the limited API
http://bugs.python.org/issue29086

#29083: Readd PyArg_VaParse to the stable API
http://bugs.python.org/issue29083

#29081: time.str